[climacs-devel] Re: [Gardeners] RFG climacs docstrings

[John Q Splittist]

Creighton Hogg wrote:
> so a couple of days ago I volunteered on the Lisp Gardeners 
> group to work on a project involving documenting commands in 
> climacs.

My simple plan for enabling this (in the short term) would be something 
like this:

Have a hashtable that collects the docstrings:

(defvar *command-documentation* (make-hash-table))

Then create a new macro, say def-command, that fills the table:

(defmacro def-command ((name . options)
		       arguments
		       documentation
		       &body body)
   `(progn
     (setf (gethash ,name *command-documentation*) ,documentation)
     (define-command (,name , at options) ,arguments , at body)))

(or something slightly more complex that checks if DOCUMENTATION is a 
string, and, if not, omits the hashing and treats DOCUMENTATION as the 
first form of BODY.)

The form of the docstring could be something like:

"First line of the docstring, for display in the minibuffer.
A longer explanation, continuing on from the first line, that would be 
suitable for display on a help pane, once we have them."

Perhaps it will be found that further markup in the docstrings will be 
helpful.

Thoughts, anyone?

JQS

PS Creighton, many thanks for volunteering!