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

[Brian Mastenbrook]

On Dec 31, 2005, at 3:16 AM, John Q Splittist wrote:

> 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.)

I'm not sure that def-command is really a self-explanitory name. How  
about define-command/documentation, or does that offend other  
peoples' style senses?

>
> 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?

The natural form for markup would be to make the documentation a  
function which, when invoked, draws the documentation (or the  
extended documentation) to a pane argument. A few macros could be  
supplied to create this lambda without actually having to write out  
all the CLIM drawing commands.

--
Brian Mastenbrook
brian at mastenbrook.net
http://brian.mastenbrook.net/