Merge pull request #2 from JoshuaKento/codex/add-readme.md-to-root-directory-05s46v

Add documentation comments to Mamdani inference components

Author: JoshuaKento

README.md

@@ -1,5 +1,6 @@
 # rust-fuzzylogic
 
+
 A Rust crate that provides building blocks for authoring fuzzy inference systems.
 The project aims to make it easy to describe linguistic variables, membership functions, and rule
 bases while keeping room for experimentation with multiple aggregation operators and inference

src/aggregate.rs

@@ -1,14 +1,16 @@
-//Agregation acros sets of rules
+// Aggregation utilities for combining rule outputs across consequents.
 
 use crate::{mamdani::Rule, prelude::*, variable::Variable};
 use std::{borrow::Borrow, collections::HashMap, hash::Hash};
 
+/// Combine two membership sample vectors by taking the pointwise maximum.
 pub fn elements_max(data: &mut Vec<Float>, src: &Vec<Float>) {
     for (d, s) in data.iter_mut().zip(src) {
         *d = d.max(*s)
     }
 }
 
+/// Aggregate the contributions of all rules into output membership functions.
 pub fn aggregation<KI, KV>(
     rules: Vec<Rule>,
     input: &HashMap<KI, Float>,

src/defuzz.rs

@@ -1,7 +1,8 @@
-//Possible Defuzz methods => Bisecctor of Area, Centroid, ...
+// Defuzzification utilities for collapsing aggregated membership values.
 use crate::{prelude::*, variable::Variable};
 use std::{borrow::Borrow, collections::HashMap, hash::Hash};
 
+/// Defuzzify aggregated membership samples using the centroid of area method.
 pub fn defuzzification<KV>(
     myu: HashMap<String, Vec<Float>>,
     vars: &HashMap<KV, Variable>,

src/mamdani.rs

@@ -1,4 +1,4 @@
-//mamdani style Implication and Consequent/Rule Behaviour
+// Mamdani-style implication and rule behavior primitives.
 
 use std::{borrow::Borrow, collections::HashMap, hash::Hash};
 
@@ -11,18 +11,21 @@ use crate::{
     variable::Variable,
 };
 
+/// Implication modes supported by a Mamdani rule.
 pub enum Implication {
     Clip,
     Product,
 }
 
+/// Output clause of a fuzzy rule referencing a linguistic variable and term.
 pub struct Consequent {
     pub var: String,
     pub term: String,
     //pub weight: Float,
     //pub imp: Implication,
 }
 
+/// Full fuzzy rule pairing an antecedent with one or more consequents.
 pub struct Rule {
     pub antecedent: Antecedent,
     pub consequent: Vec<Consequent>,
@@ -31,6 +34,7 @@ pub struct Rule {
 //Mamdani Inference Engine
 #[cfg(feature = "inference-mamdani")]
 impl Rule {
+    /// Evaluate the antecedent against crisp input values to obtain activation.
     pub fn activation<KI, KV>(
         &self,
         input: &HashMap<KI, Float>,
@@ -43,6 +47,7 @@ impl Rule {
         eval_antecedent(&self.antecedent, input, vars)
     }
 
+    /// Apply the selected implication operator to produce discretized membership outputs.
     pub fn implicate<KV>(
         &self,
         alpha: Float,

src/rulespace.rs

@@ -10,14 +10,15 @@ use crate::{
     variable::Variable,
 };
 
-//#[derive()]
+// Container for fuzzy variables, rules, and intermediate membership data.
 pub struct RuleSpace {
     pub vars: HashMap<String, Variable>,
     pub myu: HashMap<String, Vec<Float>>,
     pub rules: Vec<Rule>,
 }
 
 impl RuleSpace {
+    /// Create a rule space with the supplied variables and rules.
     pub fn new(self, vars: HashMap<String, Variable>, rules: Vec<Rule>) -> Self {
         return Self {
             vars: vars,
@@ -26,10 +27,12 @@ impl RuleSpace {
         };
     }
 
+    /// Append additional rules to the existing rule set.
     pub fn add_rules(mut self, rules: &mut Vec<Rule>) {
         self.rules.append(rules);
     }
 
+    /// Run the aggregation step for all rules with the provided crisp inputs.
     pub fn aggregate<KI>(
         &mut self,
         input: &HashMap<KI, Float>,
@@ -45,6 +48,7 @@ impl RuleSpace {
         Ok(())
     }
 
+    /// Aggregate and then defuzzify each output variable using the supplied sampler.
     pub fn defuzzificate<KI>(
         &mut self,
         input: &HashMap<KI, Float>,