Commits

Anonymous committed ddbfa00

Starting writing docs.

  • Participants
  • Parent commits df847bf

Comments (0)

Files changed (1)

                           #:standard-generic-function
                           #:defmethod
                           #:defgeneric
-                          #:standard-class))
+                          #:standard-class)
+  (:documentation
+   "* Description
+CLOD is a tool for creating documentation for Common Lisp programs."))
 
 (in-package :clod)
 
-(defvar *out* nil)
-(defvar *heading-level* 0)
-(defvar *heading-char* #\*)
-(defvar *line-width* 80)
-(defvar *left-margin* 0)
-(deftype =entity= () `(member :slot :generic-function :function :macro
-                              :constant :variable :class
-                              :structure :package
-                              :slot-accessor :slot-writer :slot-reader))
+(defvar *out* nil
+  "* Description
+Global variable that is bound to the output stream used by CLOD
+when writing documentation.")
+(defvar *heading-level* 0
+  "* Description
+Number of levels 'deep' within the outline.")
+(defvar *heading-char* #\*
+  "* Description
+Character used at the beginning of lines to signify headings and
+subheadings.")
+(defvar *line-width* 80
+  "* Description
+Width to which paragraphs are wrapped.")
+(defvar *left-margin* 0
+  "* Description
+Number of spaces to which text is currently being indented.")
+(deftype =entity= ()
+  "* Description
+Type for entities."
+  `(member :slot :generic-function :function :macro
+           :constant :variable :class
+           :structure :package
+           :slot-accessor :slot-writer :slot-reader))
 
 
-(defgeneric document (sym doctype))
+(defgeneric document (sym doctype)
+  (:documentation
+   "* Arguments
+- SYM: a symbol.
+- DOCTYPE: an [[=ENTITY=]].
+* Returns:
+Nil.
+* Description
+Write a section documenting the entity named SYM which is of entity type
+DOCTYPE."))
 
 ;; todo still unclear how to tell if a symbol is bound to a type.
 ;; eg (deftype =foo= () `(integer 0 10))
 
 
 (defun entity->tag (entity)
+  "* Arguments
+- ENTITY: An [[=ENTITY=]].
+* Returns
+A string.
+* Description
+Given an entity, returns a string that can be used as a tag in org mode."
   (case entity
     (:generic-function "generic")
     (:function "function")
     (for term in terms)
     (for spec = (pop specs))
     (if spec
-        (collect (list term (make-link (class-name spec) :linktype :class)))
+        (collect (list term (make-link (if (typep spec 'class)
+                                           (class-name spec)
+                                           (class-name (class-of spec)))
+                                       :linktype :class)))
         (collect term))))
 
 
 
 
 (defun write-heading (title)
-  (format *out* "~&~A ~A~%~%"
+  (format *out* "~%~A ~A~%~%"
            (make-string *heading-level* :initial-element *heading-char*)
            title))