added-comment-on-functions

attention-bank/attention-value/getter-and-setter.metta

@@ -148,4 +148,3 @@
 )
 
 (= (getType $pattern) (get-type $pattern))
-

attention-bank/bank/atom-bins/atombins.metta

@@ -19,6 +19,19 @@
 ; Function to insert an atom into the specifc bin
 !(bind! &atombin (new-space))
 
+;Function: insertAtom
+;Description: Inserts an atom into the specified bin index within &atombin space.
+;             If the atom's type is undefined(ifthe atom has neither AV nor STV)
+;             , it returns an error message.
+;             If the bin(the index of the bin in which the atom is to be inserted to)is empty, 
+;             it creates a new bin and adds the atom.
+;             Otherwise, it updates the existing bin by adding the new atom.
+;Parameters:
+;         $bin_index: The index of the bin where the atom should be inserted.
+;         $pattern: The atom to be inserted.
+;Returns: A confirmation message ("Atom Inserted") if successful, 
+;         or an error message if the atom is invalid.
+
 (: insertAtom (-> Number Atom empty))
 (= (insertAtom $bin_index $pattern)
    (if(== (getType $pattern) %Undefined%)
@@ -41,7 +54,18 @@
    )
 )
 
-;Function to remove an atom from a specific bin
+;Function: removeAtom
+;Description: Removes a specified atom from a given bin from &atombin space.
+;            If the atom's type is undefined (if the atom has neither AV nor STV), 
+;            it returns an error message.
+;            If the bin is empty, it returns a message indicating that there is nothing to remove.
+;            Otherwise, it updates the bin by removing the specified atom.
+;Parameters:
+;          $bin_index: The index of the bin from which the atom should be removed.
+;          $atom: The atom to be removed.
+;Returns: A confirmation message ("Atom Removed") if successful, 
+;         or an error message if the atom is invalid or the bin is empty.
+
 (: removeAtom (-> Number Atom empty))
 (= (removeAtom $bin_index $atom)
    (if (== (getType $atom) %Undefined%)
@@ -50,8 +74,6 @@
          (if(== $bin_contents ())
             ("Bin is empty") ; Bin is empty, nothing to remove
             (let $updated_contents (remove_atom_helper $atom (car-atom $bin_contents))
-               ;(if (== $updated_contents ())
-               ;   (remove-atom &atombin ($bin_index $bin_contents)) ; Remove empty bin
                   (match &atombin ($bin_index $x)
                      (let*
                        (
@@ -61,15 +83,21 @@
                       ("Atom Removed")
                      )
                   )
-               ;)
+
             )
          )
       )
    )
 )
 
+;Function: remove_atom_helper
+;Description: Recursively removes a specified atom from a list of contents.
+;             If the atom is found, it is skipped in the resulting list.
+;Parameters:
+;          $atom: The atom to be removed.
+;          $contents: The list of atoms from which to remove the specified atom.
+;Returns: A new list with all occurrences of the specified atom removed.
 
-; Helper function to remove an atom from a list of contents
 (: remove_atom_helper (-> Atom List List))
 (= (remove_atom_helper $atom $contents)
    (if(== $contents ())

attention-bank/bank/atom-bins/get-min-max-content.metta

@@ -34,19 +34,28 @@
     )
 )
 
-; Calculates the total number of atoms across all bins in &atombin
+;Function: binSize
+;Description: Calculates the total number of atoms across all bins in &atombin space.
+;             It retrieves all bin indices and computes the cumulative sum of their sizes.
+;Parameters: None.
+;Returns: The total number of atoms across all bins.
 (: binSize (-> Number))
 (= (binSize)
    (let* (
       ($atombin (AtomBin))
       ($indices (collapse (match $atombin ($x $y) $x)))
-      ($binsSize (sumSizes $indices)) ;cumulative sum of all sizes of bins in atombin
+      ($binsSize (sumSizes $indices)) 
     )
     $binsSize
   )
 )
 
-; Recursively sums the sizes of all bins in a list of bins
+;Function: sumSizes
+;Description: Recursively computes the total number of atoms across all bins in a given list of bin indices.
+;             It iterates through the list of indices, retrieves the size of each bin, and sums them up.
+;Parameters:
+;          $indices: A list of bin indices whose sizes should be summed.
+;Returns: The cumulative size of all bins in the given list.
 (: sumSizes (-> Expression Number))
 (= (sumSizes $indices)
    (if (== $indices ())

attention-bank/bank/attention-bank.metta

@@ -1,4 +1,3 @@
-; Define initial variables and insert them in newspace called space
 !(bind! &space (new-space))
 !(add-atom &space (startingFundsSTI 100000))
 !(add-atom &space (fundsSTI 100000))
@@ -12,28 +11,13 @@
 !(add-atom &space (LTIAtomWage 10))
 
 
-; Function to compute the minimum of two values
-;(: min (-> Number Number Number))
-;(= (min $a $b)
-;    (if (< $a $b) $a $b)
-;)
-
-; Function to compute the maximum of two values
-;(: max (-> Number Number Number))
-;(= (max $a $b)
-;    (if (> $a $b) $a $b)
-;)
-
 ; Function to calculate STI wage
-; Purpose:
-;    Calculates the adjustment factor for Short-Term Importance (STI) based on:
-;    - Current STI funds
-;    - Target STI funds
-;    - The buffer for STI adjustments
-; Logic:
+; Description: Calculates the adjustment factor for Short-Term Importance (STI)
 ;    - Compute the normalized difference between current funds and the target.
 ;    - Limit the adjustment factor between -1.0 and 1.0.
 ;    - Return the adjusted STI wage.
+; Parameters: None.
+; Returns: The adjusted STI wage value.
 (: calculateSTIWage (-> Number))
 (= (calculateSTIWage)
    (let* (
@@ -52,15 +36,13 @@
 )
 
 ; Function to calculate LTI wage
-; Purpose:
-;    Calculates the adjustment factor for Long-Term Importance (LTI) based on:
-;    - Current LTI funds
-;    - Target LTI funds
-;    - The buffer for LTI adjustments
-; Logic:
+; Description:
+;   Calculates the adjustment factor for Long-Term Importance (LTI)
 ;    - Compute the normalized difference between current funds and the target.
 ;    - Limit the adjustment factor between -1.0 and 1.0.
 ;    - Return the adjusted LTI wage.
+; Parameters: None.
+; Returns: The adjusted LTI wage value
 (: calculateLTIWage (-> Number))
 (= (calculateLTIWage)
    (let* (
@@ -79,14 +61,15 @@
 )
 
 ; Function to stimulate an atom with a given stimulus
-; Purpose:
+; Description:
 ;    Adjusts the AttentionValue (STI, LTI, VLTI) of an atom based on:
-;    - Calculated STI and LTI wages
-;    - A stimulus factor
-; Logic:
 ;    - Calculate the new STI and LTI values using the wages and stimulus.
 ;    - Calculate the changes in STI and LTI funds.
 ;    - Call attentionValueChanged to apply the updates.
+;Parameters:
+;     $pattern: The atom receiving the stimulus.
+;     $stimulus: The factor by which STI and LTI will be adjusted.
+;Returns: Nothing (updates the atom and related values)
 (: stimulate (-> Atom Number empty))
 (= (stimulate $pattern $stimulus)
    (let* (
@@ -111,12 +94,20 @@
 )
 
 ; Function to handle attention value changes and update global funds
-; Purpose:
-;    Updates the AttentionValue of an atom and adjusts the global STI and LTI funds.
-; Logic:
+; Description:
+;    Updates the AttentionValue of an atom and adjusts the global STI and LTI funds
 ;    -set the new attention value of the atom 
 ;    - Remove the current fundsSTI and fundsLTI values from the AtomSpace.
 ;    - Add the updated fundsSTI and fundsLTI values to the AtomSpace.
+;    - Inserts the atom to the attentional focus if possible
+;    - Updates the Bin placement of the atom
+;Parameters:
+;     $pattern: The atom whose AttentionValue is being updated.
+;     $newSTIFund: The new STI fund value.
+;     $newLTIFund: The new LTI fund value.
+;     $newAv: The new AttentionValue to be set for the atom.
+;Returns: The result of updating the AtomBin.
+
 
 (: attentionValueChanged (-> Atom Number Number AttentionValue empty))
 (= (attentionValueChanged $pattern $newSTIFund $newLTIFund $newAv)
@@ -134,6 +125,13 @@
     )
 )
 
+;Function: updateLTIFunds
+;Description: Updates the global LTI funds by replacing the old value with a new one
+;Parameters:
+;     $old: The previous LTI fund value
+;     $new: The new LTI fund value
+;Returns: Nothing (updates the fund in the AtomSpace)
+
 (: updateLTIFunds (-> Number Number empty))
 (= (updateLTIFunds $old $new)
   (match  &space  (fundsLTI $old)
@@ -144,6 +142,12 @@
   )
 )
 
+;Function: updateSTIFunds
+;Description: Updates the global STI funds by replacing the old value with a new one.
+;Parameters:
+;      $old: The previous STI fund value.
+;      $new: The new STI fund value.
+;Returns: Nothing (updates the fund in the AtomSpace).
 (: updateSTIFunds (-> Number Number empty))
 (= (updateSTIFunds $old $new)
   (match  &space  (fundsSTI $old)

attention-bank/bank/attentional-focus/attentional-focus.metta

@@ -2,7 +2,11 @@
 
 (= (maxAFSize) 100)
 
-;checks if an atom is in attentional focus
+;Function: atomIsInAF
+;Description: Checks if a given atom is in the attentional focus space.
+;Parameters:
+;         $atom: The atom to check.
+;Returns: True if the atom is in attentional focus space, otherwise False.
 
 (: atomIsInAF (-> Atom Bool))
 (= (atomIsInAF $atom)
@@ -12,15 +16,25 @@
     )
 )
 
-;checks if an atom is in attentional focus
+;Function: atomIsNotInAF
+;Description: Checks if a given atom is NOT in the attentional focus.
+;Parameters:
+;          $atom: The atom to check.
+;Returns: True if the atom is not in attentional focus, otherwise False.
 
 (: atomIsNotInAF (-> Atom Bool))
 (= (atomIsNotInAF $atom)
    (not (atomIsInAF $atom))
 )
 
-;adds an atom to the attentional focus if it is valid
 
+;Function: addAtomToAF
+;Description:
+;           if the atom has neither AV nor STV,it returns an error message
+;           if an atom is valid,it will add it to the attentional focus space. 
+;Parameters:
+;          $atom: The atom to add.
+;Returns: A message indicating success or failure.
 (: addAtomToAF (-> Atom Symbol))
 (= (addAtomToAF $atom)
    (if (== (getType $atom) %Undefined%)
@@ -32,24 +46,32 @@
    )
 )
 
-; Collapse space to list of atoms
-
+;Function: getAtomList
+;Description: Retrieves a list of all atoms currently in attentional focus space.
+;Parameters: None.
+;Returns: A list of atoms in attentional focus space.
 (: getAtomList(->Symbol))
 (= (getAtomList)
    (collapse (get-atoms &attentionalFocus))
 )
 
-;it returns the total number of atoms in the attentional focus
-
+;Function: attentionalFocusSize
+;Description: Returns the total number of atoms in the attentional focus space
+;Parameters: None
+;Returns: The number of atoms in attentional focus space
 (: attentionalFocusSize (-> Number))
 (= (attentionalFocusSize)
    (let $atomList (getAtomList)
     (size-atom $atomList)
    )
 )
 
-; Helper function for filtering atoms with STI less than the pivot
-
+;Function: lessThanSti
+;Description: Helper function that checks if the STI of $elem is less than the STI of $pivot.
+;Parameters:
+;         $elem: The first atom.
+;         $pivot: The atom to compare against.
+;Returns: True if $elem has a lower STI than $pivot, otherwise False.
 (: lessThanSti (-> Atom Atom Bool))
 (= (lessThanSti $elem $pivot)
     (if (or (== $elem ()) (== $pivot ())) 
@@ -58,7 +80,13 @@
     )
 )
 
-; Helper function for filtering atoms with STI greater than or equal to the pivot
+;Function: greaterEqualSti
+;Description: Helper function that checks if the STI of $elem is greater than or equal to the STI of $pivot.
+;Parameters:
+;        $elem: The first atom.
+;        $pivot: The atom to compare against.
+;Returns: True if $elem has an equal or higher STI than $pivot, otherwise False.
+
 
 (: greaterEqualSti (-> Atom Atom Bool))
 (= (greaterEqualSti $elem $pivot)
@@ -68,7 +96,11 @@
     )
 )
 
-; Sorts a list of atoms by their STI values in ascending order
+;Function: sortAtomsBySti
+;Description: Sorts a list of atoms by their STI values in ascending order using recursive filtering.
+;Parameters:
+;         $atoms: A list of atoms.
+;Returns: A sorted list of atoms in ascending order of STI.
 
 (: sortAtomsBySti (-> Symbol Symbol))
 (= (sortAtomsBySti $atoms)
@@ -88,8 +120,11 @@
     )
 )
 
-; Sorts a list of atoms by their STI values in descending order
-
+;Function: sortAtomsByStiDescending
+;Description:Sorts a list of atoms by their STI values in descending order using recursive filtering.
+;Parameters:
+;         $atoms: A list of atoms.
+;Returns: A sorted list of atoms in descending order of STI.
 (: sortAtomsByStiDescending (-> Symbol Symbol))
 (= (sortAtomsByStiDescending $atoms)
     (if (== $atoms ())
@@ -108,9 +143,7 @@
     )
 )
 
-;gets the atom with the lowest STI value in the attentional focus
 
-;(: getLowestStiAtomInAFHelper (-> List Atom Number Atom))
 (= (getLowestStiAtomInAFHelper $atoms $minAtom $minSTI)
     (if (== $atoms ())
         $minAtom
@@ -165,6 +198,12 @@
 ;serve logging the additional and removal of an atom as i reviewed in the example/AtomSpaceEventSubscribeExample.cc
 ;and we may implement it in the future if needed
 
+;Function: updateAttentionalFocus
+;Description: Updates the attentional focus by adding a new atom, 
+;             or replacing the lowest STI atom if the attentional focus is full.
+;Parameters:
+;          $atom: The atom to be added or updated.
+;Returns: Nothing if no update occurs, otherwise the atom is added.
 (: updateAttentionalFocus (-> Atom empty))
 (= (updateAttentionalFocus $atom)
    (let*
@@ -199,8 +238,10 @@
    )
 )
 
-; Function to retrieve a random atom not in attentional focus
-
+;Function: getRandomAtomNotInAF
+;Description: Retrieves a random atom that is not in attentional focus.
+;Parameters: None.
+;Returns: A randomly selected atom from outside attentional focus.
 (: getRandomAtomNotInAF (-> Atom))
 (= (getRandomAtomNotInAF)
    (let*