Documentation updates.

exports.lisp

@@ -1,10 +1,19 @@
 (
 
+ ?
+
  2CMBN-ADD
  2CMBN-SBTR
  2N-2CMBN
 
+ ALL-OBJECTS
+
+ BASIS
+ BUILD-CHCM
+
+ CAT-INIT
  CHECK-CMBN
+ CHCM
  CMBN
  CMBN-CMBN
  CMBN-DEGR
@@ -13,9 +22,18 @@
  CMBN-OPPS
  CMBN-PRINT
  CMBN-ZERO-P
+ CMPR
+
+ DFFR
 
  F-CMPR
 
+ HOW-MANY-OBJECTS
+
+ K
+ KD
+ KD2
+
  L-CMPR
 
  N-CMBN
@@ -27,6 +45,7 @@
  TERM-CMBN
 
  ZERO-CMBN
+ ZERO-INTR-DFFR
  ZERO-PURE-DFFR
 
  )

src/chain-complexes.lisp

@@ -6,10 +6,15 @@
 
 (PROVIDE "chain-complexes")
 
+
 (DEFUN CAT-INIT ()
   (declare (special *idnm-counter* *results-n* *results-cmlt-tm*))
-  "Clear the list of user created chain complexes *CHCM-LIST* and reset the
+  "--------------------------------------------------------------[function-doc]
-global counter to 0."
+CAT-INIT
+Args: ()
+Clear the list of user created chain complexes *CHCM-LIST* and reset the
+global counter to 0.
+------------------------------------------------------------------------------"
   (setf *idnm-counter* 0 *results-n* 0 *results-cmlt-tm* 0.0)
   (map nil #'(lambda (listname)
                (declare (symbol listname))
@@ -17,8 +22,13 @@ global counter to 0."
        *list-list*)
   (done))
 
+
 (DEFUN HOW-MANY-OBJECTS ()
-  "Return the number of user created objects by object type."
+  "--------------------------------------------------------------[function-doc]
+HOW-MANY-OBJECTS
+Args: ()
+Return the number of user created objects by object type.
+------------------------------------------------------------------------------"
   (mapc #'(lambda (symbol)
 	    (declare (type (or string symbol) symbol))
 	    (let ((length (length (eval symbol))))
@@ -29,8 +39,13 @@ global counter to 0."
 	*list-list*)
   (done))
 
+
 (DEFUN ALL-OBJECTS ()
-  "Return a string representation of a user created objects."
+  "--------------------------------------------------------------[function-doc]
+ALL-OBJECTS
+Args: ()
+Return a string representation of a user created objects.
+------------------------------------------------------------------------------"
   (let ((object-list
 	 (sort (delete-duplicates
 		(mapcan #'(lambda (symbol)
@@ -43,10 +58,15 @@ global counter to 0."
       (format t "~%~A = ~A" item (orgn item))))
   (done))
 
+
 (DEFUN KD (idnm)
   (declare (fixnum idnm))
-  "Return the type of Kenzo object number IDNM and print the comment list
+  "--------------------------------------------------------------[function-doc]
-(SLOT :ORGN) of the object."
+KD
+Args: (idnm)
+Return the type of Kenzo object number IDNM and print the comment list
+(SLOT :ORGN) of the object.
+------------------------------------------------------------------------------"
   (dolist (list *list-list*)
     (let ((found (find idnm (eval list) :key #'idnm)))
       (when found
@@ -54,20 +74,30 @@ global counter to 0."
 ~3TOrigin: ~A~2%" found (orgn found))
 	(return-from kd (values))))))
 
+
 (DEFUN K (idnm)
   (declare (fixnum idnm))
-  "Get the IDNM-th Kenzo object."
+  "--------------------------------------------------------------[function-doc]
+K
+Args: (idnm)
+Returns the IDNM-th Kenzo object.
+------------------------------------------------------------------------------"
   (dolist (list *list-list*)
     (let ((found (find idnm (eval list) :key #'idnm)))
       (when found
 	(return-from k found)))))
 
+
 (DEFUN KD2 (idnm)
   (declare (fixnum idnm))
-  "Return the type of Kenzo object number IDNM, print the comment list
+  "--------------------------------------------------------------[function-doc]
+KD2
+Args: (idnm)
+Return the type of Kenzo object number IDNM, print the comment list
 (SLOT :ORGN) of the object and, recursively, return the same information
 for all Kenzo objects of the same type in relation with this object. Return
-the list of object numbers."
+the list of object numbers.
+------------------------------------------------------------------------------"
   (let ((k-list (k idnm)))
     (declare (list k-list))
     (unless k-list
@@ -97,13 +127,19 @@ the list of object numbers."
 #+clisp(eval-when (:compile-toplevel :load-toplevel :execute)
          (setf (ext:package-lock :clos) t))
 
+
 (DEFUN CHCM (idnm)
   (declare (fixnum idnm))
-  "Return from the list *CHCM-LIST* the chain complex instance with Kenzo
+  "--------------------------------------------------------------[function-doc]
-identifier IDNUM or NIL, if it doesn't exist."
+CHCM
+Args: (idnm)
+Return from the list *CHCM-LIST* the chain complex instance with Kenzo
+identifier IDNUM or NIL, if it doesn't exist.
+------------------------------------------------------------------------------"
   (the (or chain-complex null)
        (find idnm *chcm-list* :key #'idnm)))
 
+
 (DEFUN RESULT-PRINT (result stream depth)
   (declare
    (type result result) (stream stream)
@@ -117,21 +153,26 @@ identifier IDNUM or NIL, if it doesn't exist."
 	  (result-clnm result) (result-rntm result))
   result)
 
+
 (DEFGENERIC ?2 (chcm-or-mrph cmbn))
 
+
 (DEFMETHOD ?2 ((mrph morphism) cmbn)
   (declare (type cmbn cmbn))
   (the cmbn
        (cmbn-? mrph cmbn)))
 
+
 (DEFMETHOD ?2 ((chcm chain-complex) cmbn)
   (declare
    (type cmbn cmbn))
   (the cmbn
        (cmbn-? (dffr1 chcm) cmbn)))
 
+
 (DEFGENERIC ?3 (chcm-or-mrph degr gnrt))
 
+
 (DEFMETHOD ?3 ((mrph morphism) degr gnrt)
   (declare
    (fixnum degr)
@@ -139,12 +180,14 @@ identifier IDNUM or NIL, if it doesn't exist."
   (the cmbn
        (gnrt-? mrph degr gnrt)))
 
+
 (DEFMETHOD ?3 ((chcm chain-complex) degr gnrt)
   (declare
    (fixnum degr)
    (type gnrt gnrt))
   (gnrt-? (dffr1 chcm) degr gnrt))
 
+
 #+clisp(eval-when (:compile-toplevel :load-toplevel :execute)
          (setf (ext:package-lock :clos) nil))
 (DEFMETHOD PRINT-OBJECT ((mrph morphism) stream)
@@ -167,6 +210,7 @@ IDNUM or NIL, if it doesn't exist."
   (the (or morphism null)
        (find n *mrph-list* :key #'idnm)))
 
+
 (DEFUN BUILD-CHCM (&key cmpr basis bsgn intr-dffr strt orgn)
   (declare
    (type cmprf cmpr)
@@ -175,8 +219,12 @@ IDNUM or NIL, if it doesn't exist."
    (type (or intr-mrph null) intr-dffr)
    (type strt strt)
    (type list orgn))
-  "Returns an instance of CHAIN-COMPLEX. Use this function instead of creating
+  "--------------------------------------------------------------[function-doc]
-instances via the standard constructor MAKE-INSTANCE."
+BUILD-CHCM
+Args: (&key cmpr basis bsgn intr-dffr strt orgn)
+Returns an instance of CHAIN-COMPLEX. Use this function instead of creating
+instances via the standard constructor MAKE-INSTANCE.
+------------------------------------------------------------------------------"
   (the chain-complex
        (progn
          (let ((already (find orgn *chcm-list* :test #'equal :key #'orgn)))
@@ -200,6 +248,7 @@ instances via the standard constructor MAKE-INSTANCE."
 	   (push chcm *chcm-list*)
 	   chcm))))
 
+
 (DEFUN BASIS2 (object n)         ;;;
   (declare
    (type t object)
@@ -211,6 +260,7 @@ instances via the standard constructor MAKE-INSTANCE."
 	   (error "The object ~A is locally-effective." object))
          (funcall basis n))))
 
+
 (DEFUN BUILD-MRPH (&key sorc trgt degr intr strt orgn)
   (declare
    (type chain-complex sorc trgt)

src/chcm-elementary-op.lisp

@@ -7,7 +7,11 @@
 (PROVIDE "chcm-elementary-op")
 
 (DEFUN Z-CHCM ()
-  "Build the unit chain complex."
+  "--------------------------------------------------------------[function-doc]
+Z-CHCM
+Args: ()
+Build the unit chain complex.
+------------------------------------------------------------------------------"
   (the chain-complex
        (build-chcm
 	:cmpr #'(lambda (gnrt1 gnrt2)

src/combinations.lisp

@@ -202,6 +202,12 @@ degree -1.
 
 (DEFUN ZERO-INTR-DFFR (cmbn)
   (declare (type cmbn cmbn))
+  "--------------------------------------------------------------[function-doc]
+ZERO-INTR-DFFR
+Args: (cmbn)
+Returns the null combination of degree p-1, for any combination CMBN of
+degree p.
+------------------------------------------------------------------------------"
   (the cmbn (zero-cmbn (1- (cmbn-degr cmbn)))))
 
 

src/macros.lisp

@@ -147,6 +147,14 @@ Tests if the combination CMBN is the null combination of any degree.
 ;;;
 
 (DEFMACRO CMPR (&rest rest)
+  "------------------------------------------------------------------[macro-doc]
+CMPR
+Args: (&rest rest)
+Args: (chcm gnrt1 gnrt2)
+Typically invoked with a chain complex CHCM and two generators GNRT1 and GNRT2.
+Applies the comparison function associated with CHCM to GNRT1 and GNRT2, and
+return the result.
+------------------------------------------------------------------------------"
   (ecase (length rest)
     (1 `(cmpr1 ,@rest))
     (3 `(cmpr3 ,@rest))))
@@ -157,6 +165,20 @@ Tests if the combination CMBN is the null combination of any degree.
 
 
 (DEFMACRO BASIS (&rest rest)
+  "------------------------------------------------------------------[macro-doc]
+BASIS
+Args: (&rest rest)
+Args: (chcm)
+Args: (chcm n)
+Args: (chcm n :dgnr)
+When invoked with only one argument, returns the function attached to the slot
+BASIS of the chain complex.
+When invoked with two arguments, returns the basis of the group of degree N of
+ the chain complex.
+When invoked with three arguments, the keyword :DGNR, it also returns the
+degenerate elements of the basis in degree N.
+This function returns an error if the chain complex is locally effective.
+------------------------------------------------------------------------------"
   (ecase (length rest)
     (1 `(basis1 ,@rest))
     (2 `(basis2 ,@rest))
@@ -169,6 +191,15 @@ Tests if the combination CMBN is the null combination of any degree.
 
 
 (DEFMACRO DFFR (&rest rest)
+  "------------------------------------------------------------------[macro-doc]
+DFFR
+Args: (&rest rest)
+Args: (chcm cmbn)
+Args: (chcm degr gnrt)
+Applies the differential morphism of the chain complex CHCM to a combination
+CMBN or a generator GNRT of a degree DEGR.
+See also the macro ?.
+------------------------------------------------------------------------------"
   (ecase (length rest)
     (1 `(dffr1 ,@rest))
     ((2 3) `(? (dffr1 ,(first rest)) ,@(rest rest)))))