current status of documentation

lib/src/metta/runner/stdlib.metta

@@ -1,4 +1,5 @@
-(@doc = 
+; TODO: for some reason get-doc doesn't work for '='
+(@doc =
   (@desc "A symbol used to define reduction rules for expressions.")
   (@params (
     (@param "Pattern to be matched against expression to be reduced")
@@ -45,8 +46,14 @@
   (@return "Quoted atom"))
 (: quote (-> Atom Atom))
 
-; unify matches two atoms and returns $then if they are matched
-; and $else otherwise.
+(@doc unify
+  (@desc "Matches two atoms and returns $then if they are matched and $else otherwise")
+  (@params (
+    (@param "First atom to unify with")
+    (@param "Second atom to unify with")
+    (@param "Result if two atoms unified successfully")
+    (@param "Result otherwise")))
+  (@return "Unit atom"))
 (: unify (-> Atom Atom Atom Atom %Undefined%))
 (= (unify $a $a $then $else) $then)
 (= (unify $a $b $then $else)
@@ -55,46 +62,126 @@
 (= (unify-or-empty $a $a) unified)
 (= (unify-or-empty $a $b) (empty))
 
-; empty removes current result from a non-deterministic result
+(@doc empty
+  (@desc "Removes current result from a non-deterministic result")
+  (@return "Empty [] brackets"))
 (: empty (-> %Undefined%))
 (= (empty) (let a b never-happens))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ; Documentation formatting functions
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
+(@doc @doc
+  (@desc "Used for documentation purposes. Function documentation starts with @doc")
+  (@params (
+    (@param "Function name")
+    (@param "Function description. Starts with @desc")
+    (@param "(Optional) parameters description starting with @params which should contain one or more @param symbols")
+    (@param "(Optional) description of what function will return. Starts with @return")))
+  (@return "Function documentation using @doc-formal"))
 (: @doc (-> Atom DocDescription DocInformal))
 (: @doc (-> Atom DocDescription DocParameters DocReturnInformal DocInformal))
+
+(@doc @desc
+  (@desc "Used for documentation purposes. Description of function starts with @desc as a part of @doc")
+  (@params (
+    (@param "String containing function description")))
+  (@return "Function description"))
 (: @desc (-> String DocDescription))
+
+;(@doc @param
+;  (@desc "Used for documentation purposes. Description of function parameter starts with @param as a part of @params which is a part of @doc")
+;  (@params (
+;    (@param "String containing parameter description")))
+;  (@return "Parameter description"))
 (: @param (-> String DocParameterInformal))
+(: @param (-> DocType DocDescription DocParameter))
+
+;(@doc @return
+;  (@desc "Used for documentation purposes. Description of function return value starts with @return as a part of @doc")
+;  (@params (
+;    (@param "String containing return value description")))
+;  (@return "Return value description"))
 (: @return (-> String DocReturnInformal))
+(: @return (-> DocType DocDescription DocReturn))
 
+(@doc @doc-formal
+  (@desc "Used for documentation purposes. get-doc returns documentation starting with @doc-formal symbol. @doc-formal contains 6 or 4 parameters depending on the entity being described (functions being described using 6 parameters, atoms - 4 parameters)")
+  (@params (
+    (@param "DocItem. Function/Atom name for which documentation is to be displayed. Format (@item name)")
+    (@param "DocKindAtom/DocKindFunction. Contains (@kind function) or (@kind atom) depends on entity which documentation is displayed")
+    (@param "DocType. Contains type notation of function/atom")
+    (@param "DocDescription. Function/atom description")
+    (@param "DocParameters (functions only). Description of function parameters")
+    (@param "DocReturn (functions only). Description of function's return value")))
+  (@return "Expression containing full documentation on function"))
 (: @doc-formal (-> DocItem DocKindFunction DocType DocDescription DocParameters DocReturn DocFormal))
 (: @doc-formal (-> DocItem DocKindAtom DocType DocDescription DocFormal))
+
+(@doc @item
+  (@desc "Used for documentation purposes. Converts atom/function's name to DocItem")
+  (@params (
+    (@param "Atom/Function name to be documented")))
+  (@return "(@item Atom) entity"))
 (: @item (-> Atom DocItem))
+
+; get-doc not showing docs for following two functions (@kind function) and (@kind atom) for some reason.
+(@doc (@kind function)
+  (@desc "Used for documentation purposes. Shows type of entity to be documented. (@kind function) in this case")
+  (@return "(@kind function) entity"))
 (: (@kind function) DocKindFunction)
+
+(@doc (@kind atom)
+  (@desc "Used for documentation purposes. Shows type of entity to be documented. (@kind atom) in this case")
+  (@return "(@kind atom) entity"))
 (: (@kind atom) DocKindAtom)
+
+(@doc @type
+  (@desc "Used for documentation purposes. Converts atom/function's type to DocType")
+  (@params (
+    (@param "Atom/Function type to be documented")))
+  (@return "(@type Type) entity"))
 (: @type (-> Type DocType))
-(: @params (-> Expression DocParameters))
-(: @param (-> DocType DocDescription DocParameter))
-(: @return (-> DocType DocDescription DocReturn))
 
+(@doc @params
+  (@desc "Used for function documentation purposes. Contains several @param entities with description of each @param")
+  (@params (
+    (@param "Several (@param ...) entities")))
+  (@return "DocParameters containing description of all parameters of function in form of (@params ((@param ...) (@param ...) ...))"))
+(: @params (-> Expression DocParameters))
 
+(@doc get-doc
+  (@desc "Returns documentation for the given Atom/Function. It checks if given variable is an expression and evaluates get-doc-atom on the input value or get-doc-single-atom otherwise")
+  (@params (
+    (@param "Atom/Function name for which documentation is needed")))
+  (@return "Documentation for the given atom/function"))
 (: get-doc (-> Atom Atom))
 (= (get-doc $atom)
   (let $meta-type (get-metatype $atom)
     (case $meta-type (
       (Expression (get-doc-atom $atom))
       ($_ (get-doc-single-atom $atom)) ))))
 
+(@doc get-doc-single-atom
+  (@desc "Function used by get-doc to get documentation on either function or atom. It checks if input name is the name of function or atom and calls correspondent function")
+  (@params (
+    (@param "Atom/Function name for which documentation is needed")))
+  (@return "Documentation for the given atom/function"))
 (: get-doc-single-atom (-> Atom Atom))
 (= (get-doc-single-atom $atom)
   (let $top-space (mod-space! top)
   (let $type (get-type-space $top-space $atom)
     (if (is-function-type $type)
       (get-doc-function $atom $type)
-      (get-doc-atom $atom) ))))
+      (get-doc-atom $atom)))))
 
+(@doc get-doc-function
+  (@desc "Function used by get-doc-single-atom to get documentation on a function. It returns documentation on a function if it exists or default documentation with no description otherwise")
+  (@params (
+    (@param "Function name for which documentation is needed")
+    (@param "Type notation for this function")))
+  (@return "Documentation for the given function"))
 (: get-doc-function (-> Atom Type Atom))
 (= (get-doc-function $name $type)
   (let $top-space (mod-space! top)
@@ -104,13 +191,25 @@
       (@doc-formal (@item $name) (@kind function) (@type $type) $desc (@params $params') $ret')))
     (@doc-formal (@item $name) (@kind function) (@type $type) (@desc "No documentation")) )))
 
+(@doc undefined-doc-function-type
+  (@desc "Function used by get-doc-single-atom in case of absence of function's type notation")
+  (@params (
+    (@param "List of parameters for the function we want to get documentation for")))
+  (@return "List of %Undefined% number of which depends on input list size. So for two parameters function will return (%Undefined% %Undefined% %Undefined%)"))
 (: undefined-doc-function-type (-> Expression Type))
 (= (undefined-doc-function-type $params)
   (if (== () $params) (%Undefined%)
     (let $params-tail (cdr-atom $params)
     (let $tail (undefined-doc-function-type $params-tail)
       (cons-atom %Undefined% $tail) ))))
 
+(@doc get-doc-params
+  (@desc "Function used by get-doc-function to get function's parameters documentation (including return value)")
+  (@params (
+    (@param "List of parameters in form of ((@param Description) (@param Description)...)")
+    (@param "Return value's description in form of (@return Description)")
+    (@param "Type notation without -> starting symbol e.g. (Atom Atom Atom)")))
+  (@return "United list of params and return value each augmented with its type. E.g. (((@param (@type Atom) (@desc Description)) (@param (@type Atom) (@desc Description2))) (@return (@type Atom) (@desc Description)))"))
 (: get-doc-params (-> Expression Atom Expression (Expression Atom)))
 (= (get-doc-params $params $ret $types)
   (let $head-type (car-atom $types)
@@ -124,6 +223,11 @@
         (let $result-params (cons-atom (@param (@type $head-type) (@desc $param-desc)) $params')
           ($result-params $result-ret) ))))))))
 
+(@doc get-doc-atom
+  (@desc "Function used by get-doc (in case of input type Expression) and get-doc-single-atom (in case input value is not a function) to get documentation on input value")
+  (@params (
+    (@param "Atom's name to get documentation for")))
+  (@return "Documentation on input Atom"))
 (: get-doc-atom (-> Atom Atom))
 (= (get-doc-atom $atom)
   (let $top-space (mod-space! top)
@@ -138,6 +242,11 @@
 ; constructor for instance, thus in practice it matches because -> has
 ; %Undefined% type. We need to assign proper type to -> and other type
 ; constructors but it is not possible until we support vararg types.
+(@doc is-function-type
+  (@desc "Function checks if input type is a function type")
+  (@params (
+    (@param "Type notation")))
+  (@return "True if input type notation is a function type, else - otherwise"))
 (: is-function-type (-> Type Bool))
 (= (is-function-type $type)
   (let $type-meta (get-metatype $type)
@@ -147,6 +256,11 @@
           (if (== $first ->) True False) ))
       ($_ False) ))))
 
+(@doc help!
+  (@desc "Function returns documentation for input value. It uses println! to output documentation")
+  (@params (
+    (@param "Input to get documentation for")))
+  (@return "Unit value"))
 (: help! (-> Atom (->)))
 (= (help! $atom)
   (case (get-doc $atom) (
@@ -166,11 +280,22 @@
       () ))
     ($other (Error $other "Cannot match @doc-formal structure") ))))
 
+(@doc help-param!
+  (@desc "Function used by function help! to output parameters using println!")
+  (@params (
+    (@param "Parameters list")))
+  (@return "Unit value"))
 (: help-param! (-> Atom (->)))
 (= (help-param! $param)
   (let (@param (@type $type) (@desc $desc)) $param
     (println! (format-args "  {} {}" ($type $desc))) ))
 
+(@doc for-each-in-atom
+  (@desc "Applies $func to each atom in Expression")
+  (@params (
+    (@param "Expression to each atom in which function will be applied")
+    (@param "Function to apply")))
+  (@return "Unit value"))
 (: for-each-in-atom (-> Expression Atom (->)))
 (= (for-each-in-atom $expr $func)
   (if (noreduce-eq $expr ())
@@ -180,6 +305,12 @@
       (let $_ ($func $head)
       (for-each-in-atom $tail $func) )))))
 
+(@doc noreduce-eq
+  (@desc "Checks equality of two atoms without reducing them")
+  (@params (
+    (@param "First atom")
+    (@param "Second atom")))
+  (@return "True if not reduced atoms are equal, else - otherwise"))
 (: noreduce-eq (-> Atom Atom Bool))
 (= (noreduce-eq $a $b) (== (quote $a) (quote $b)))
 
@@ -192,4 +323,4 @@
   (@params (
     (@param "Atomspace to add atom into")
     (@param "Atom to add")))
-  (@return "Unit atom"))
+  (@return "Unit atom"))