Re: strops

["Greg J. Badros" <gjb at cs dot washington dot edu>]

"Reynolds, Gregg" <greynolds@datalogics.com> writes:

<snip>

> 	Any opinion on Bevan's documentation conventions (which I rather
> like):
> 
> ;;+doc
> ;;  This is
> ;;  a bunch of text
> ;;-doc
> (foo...)  ; the function definition
> 
> I also like Bevan's use of name, args, and signature for documentation,
> although I'm not entirely clear on his signature notation.

We should stick with docstrings.  It's far more important that we have a 
complete and consistent set of documentation and we need to take a
reasonably minimal road to get there so that we have something usable
for the next release.

> Here's (some of) what I'd like in function/proc/pred doco:
> 
> 	name
> 	type ( = pred | func )
> 	arity (this could be deduced from sig)
> 	type signature (including dummy names)
> 	semantic category (for lack of a better term) (= syntax | library
> syntax | rnrs lib | other lib...)
> 	synopsis (concise description of meaning)
> 
> 	Proposal:  examples/illustrations should not be included in the *.c
> or *.h files, but contained in files specifically devoted to user
> documentation.  Source code files should only include implementation
> documenation (which includes the synopsis).

I disagree.  The full documentation for a command should live in its
docstring, appropriately marked up so that we can extract examples if we
choose.  I think it'd be a great goal to aim that every procedure to
has an example.

> I did a little work on documenting strop.c last night and plan to finish up
> this weekend.  Just in case I find time to do a little experimenting, I'd
> appreciate any feedback on the above.

Let's get docstrings in the files that are still lacking them, and I'll
get the extraction system done that generates a whole manual.  Much of
the properties you name can be figured out from the function definition
itself or its marked-up docstring.

Greg J. Badros