Re: docstrings in Guile!

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

Maciej Jennifer Stachowiak <mstachow@alum.mit.edu> writes:

> "Greg J. Badros" wrote:
> > 
> > I'm happy to report that I had a productive weekend hacking Guile.  To
> > give you an idea where we're at now:
> > 
> > % ./guile
> > guile> (documentation 'library-dir)
> > (library-dir)
> > Return the directory where the Guile Scheme library files are installed.
> > E.g., may return "/usr/share/guile/1.3.5".
> > [load.c:207]
> > #t
> 
> This is excellent news.
> 
> > 
> > GUILE_PROC(scm_substring_move_x, "substring-move!", 5, 0, 0,
> 
> I hate to nitpick (well, actually I don't, but please stop me if I do it
> to excess :-) but I think having both GUILE_PROC and SCM_PROC is
> confusing,
> I would be happier if the macros were SCM_DEFINE and SCM_PROC, since the
> distinction there is more clear, and we would be sticking to the SCM_
> prefix
> and thus minimize namespace pollution.

See my changelog entry:

Sat Dec 11 18:34:12 1999  Greg J. Badros  <gjb@cs.washington.edu>

<snip>
	* *.c: Pervasive software-engineering-motivated rewrite of
 	function headers and argument checking.  Switched SCM_PROC,
 	SCM_PROC1 macros to be GUILE_PROC, GUILE_PROC1 (may change names
 	later, but was useful to keep old versions around while migrate)
 	that has docstrings and argument lists embedded in the GUILE_PROC
 	macro invocations that expand into a function header.  Use lots of
 	new SCM_VALIDATE_* macros to simplify error checking and reduce
 	tons of redundancy.  This is very similar to what I did for Scwm.

Think of it as a migration thing.  I'll probably go to SCM_DEFINE and
SCM_REGISTER_PROC.

> > I've moved all the documentation for primitives from
> > guile-doc/ref/{appendices,posix,scheme}.texi into the source code.  This
> > leaves about half of the primitives undocumented.  Also, all the markup
> > is currently still texinfo.  I don't have a problem with texinfo per se,
> > but the markup is not very descriptive or accurate.
> 
> I hope people can volunteer to go over the code and fix/add docstrings.
> Just pick a file and do it (or half a file, or whatever). No doc
> improvement
> is too small to be useful. I promise your documentation patches will
> _not_
> get dropped on the floor. I will definitely be doing some of this work
> myself
> of course.

It might be useful to coordinate this effort;  if you're going to be
submitting patches for a file, post it here before you start working on
it, and try to post the patches within a couple days (or give us what
you've got when your time disappears).

> > I'm sure there will be build problems, etc.  Please report them here,
> > but *first* tell me how great this is! :-) I've literally spent 20 hours
> > in the last two days trying to make Guile ready for the 21st century! :-)
> 
> This is really, really great! 

:-)

Greg