Re: docstrings in Guile!

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

Greg Harvey <Greg.Harvey@thezone.net> writes:

> Great! I always said there was something really cool about that Greg
> fellow, but I didn't realize I wasn't talking about myself >;'). One
> thing I would like to see, though, is a way of adding documentation to
> a file as a whole; this would be great for adding concept and
> internals documentation for bits like the garbage collector and the
> evaluator (which is not to say that it needs to be done right now, but
> it's something to think about, at least :).

We have this in Scwm and I could make sure that the "Concept" docs in
comments are extracted for Guile, too.

> 
> "Greg J. Badros" <gjb@cs.washington.edu> writes:
> 
> > It is useful to have two functions that copy in different directions so
> > that substrings can be copied back and forth within a single string.  If
> > you wish to copy text from the left-hand side of a string to the
> > right-hand side of the same string, and the source and destination
> > overlap, you must be careful to copy the rightmost characters of the
> > text first, to avoid clobbering your data.  Hence, when @var{str1} and
> > @var{str2} are the same string, you should use
> > @code{substring-move-right!} when moving text from left to right, and
> > @code{substring-move-left!}  otherwise.  If @code{str1} and @samp{str2}
> > are different strings, it does not matter which function you use.")
> 
> Actually, that's not really true anymore; it doesn't matter which one
> you use, since memmove will do things correctly in either case. The
> left and right are basically for backwards compatibility, though they
> probably should be removed in favour of one substring-move! function.

The docs that I mechanically moved from the .texi files into the source
code are *often* no longer accurate.  substring-move-left! and
substring-move-right! are both synonyms for substring-move!, but the
docs are a bit inaccurate.  My hope is that they'll actually get updated 
as people look through the code.  I'm unable to be the guy who actually
does all of this editing, though.

I encourage the submission of patches to fix and add docstrings.  In
particular, 

grep -n -B2 '^""' *.c

will report all primitives that lack documentation.  Also, almost none
of the procedures in ice-9/*.scm are documented (someone could, e.g.,
move the documentation from *.texi into those files).

Greg