Coordinating docstring work [was Re: docstring work (was: Re: should GOOPS be built-in?)]

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

ryan yeske <rcyeske@sfu.ca> writes:

> > The most important thing, though, is to not place the burden of all
> > the documentation on one person: what we may need most of all is a bit
> > of organization to prevent a whole bunch of people from documenting
> > the same things; possibly we could set up a page at gnu.org for this.
> 
> I am interested in helping out in the writing/gathering of the
> remaining undocumented primitives.  I am at a bit of a loss as to how
> to format them though.  Existing doc-strings are in TeXinfo, should
> that be the format of new ones?  Should the argument names in the
> doc-string match the C argument names?
> 
> I imagine a lot of the work is already done (in documents like
> r[45]rs.texi and others) and it would just be a matter of pasting text
> from those documents into the source code.

For now, I think it's fine to paste the text in using whatever the
source format was; we can "defer the conversion to what format?"
decision until later.  Mechanically getting the documentation in there
in human-readable form (even if inconsistently marked up) is the first
priority.  Standardization will come later.

Remember there are ice-9/*.scm files and libguile/*.c files.

Also, Greg Harvey reminded me about his quick & dirty docs that may be
helpful, too:

http://home.thezone.net/~gharvey/guile/qdocs

The key thing is to just get the text in there from a reliable source,
and don't spend time that might be wasted doing a lot of formatting or
altering the markup.

And again, let us know what you're doing before you get started on it
and try to get the patch sent off within a couple of days after you
claim the "docstring lock" on a file.

Thanks!  This is a great opportunity for everyone to give a little
something back to the Guile project!  If a half dozen people each pick
up a couple of files, this will be done in no time at all!

Greg Badros