[Openmcl-devel] Lisp DOC

Joshua TAYLOR tayloj at cs.rpi.edu
Fri Nov 14 14:14:34 UTC 2008


For smaller projects, Edi's documentation template is fairly nice, but
it usually requires a fair amount of modification afterward, e.g., if
you want the table of contents to be something other than alphabetic.
If you want something a bit more like JavaDoc, you might try CLDOC
(http://common-lisp.net/project/cldoc/):

"Unlike  Albert  it does not allow programmers to insert comments at
the source code level which are incorporated into the generated
documentation. Its goal was not to produce a LispDoc ala JavaDoc but
to create a simple and easy way to take advantage of the Lisp
documentation strings. So instead of copying and pasting it in some
commentary section with extra special documentation tool markup stuff,
the idea was to find an elegant way of parsing the doc string. "

I do recognize that I compared it Javadoc, and that they point out
that it's /not/ "ala JavaDoc", but between the style it encourages in
docstrings and the HTML output, I think there are some significant
similarities.

The CLDOC documentation (generated by CLDOC, so it's an example) is
available at http://common-lisp.net/project/cldoc/HTMLdoc/ .

//JT
(I have no affiliation with CLDOC, but I've used it in the past and
have been rather happy with the results.)

On Thu, Nov 13, 2008 at 6:57 PM, Alexander Repenning
<ralex at cs.colorado.edu> wrote:
> It is simple to write little code producing a LOT of documentation
> with Lisp. The trivial little hack below produces documentation for
> the entire CL class tree. Especially when classes
> include :documentation even the code below is somewhat useful.
> However, my real question is this. Is anybody aware of some Java DOC-
> like tool for Lisp? That is, something like that thing below but with
> formated output (e.g., HTML with style sheet)? It would seem to be
> such an obvious and simple thing to do in Lisp that I would assume it
> already exists?
>
>
> Alex
>
> ;; ---- lisp-doc.lisp -------
>
> (in-package :ccl)
>
>
> (defparameter *Classes-Documented* (make-hash-table))
>
>
> (defun RENDER-CLASS-DOC (Classes &optional (Level 0))
>   (when (not (listp Classes))
>     (render-class-doc (list Classes) Level)
>     (return-from render-class-doc))
>   (when (= Level 0) (setf *Classes-Documented* (make-hash-table)))
>   (dolist (Class Classes)
>     (when (symbolp Class) (setf Class (find-class Class)))
>     (unless (gethash (slot-value Class 'name) *Classes-Documented*)
>       (setf (gethash (slot-value Class 'name) *Classes-Documented*)
> Class)
>       (dotimes (I (* 2 Level)) (princ #\space))
>       (princ (slot-value Class 'name))
>       (let ((Documentation (documentation (slot-value Class 'name)
> 'type)))
>         (when Documentation
>           (format t ": ~A" Documentation)))
>       (terpri)
>       (let ((Slot-Names (mapcar #'slot-definition-name (class-direct-
> slots Class))))
>         (when Slot-Names
>           (dotimes (I (* 2 (+ Level 2))) (princ #\space))
>           (format t "slots: ")
>           (dolist (Slot-Name (butlast Slot-Names))
>             (format t "~:(~A~), " Slot-Name))
>           (format t "~:(~A~)" (first (last Slot-Names)))
>           (terpri)))
>       (render-class-doc (slot-value Class 'direct-subclasses) (1+
> Level)))))
>
>
>
> #| Examples:
>
>
> (render-class-doc 'number)  ;; no much :documentation here in CCL
>
>
> (render-class-doc 't) ;; same here
>
>
>
> |#
> _______________________________________________
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
> http://clozure.com/mailman/listinfo/openmcl-devel
>



-- 
=====================
Joshua Taylor
tayloj at cs.rpi.edu, jtaylor at alum.rpi.edu

"In the Mountains of New Hampshire,
   God Almighty has hung out a sign
     to show that there He makes men."
       Daniel Webster

"A lot of good things went down one time,
  back in the goodle days."
    John Hartford



More information about the Openmcl-devel mailing list