Re: docstrings in Guile!

[Maciej Jennifer Stachowiak <mstachow at alum dot mit dot edu>]

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

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

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

 - Maciej