This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Doc Tasks (was RE: docstrings in Guile!)
> Guile basically _is_ more or less doing something similar insofar as being
> in sync with the source is concerned. I am not sure about teh value of
> the value of the manual editing step. Wouldn't that allow the manual
> to fall quite out of sync with the source, if actually used?
Well, yes. However, the point of manual editing is that you can
include complex stuff like tables and extended descriptions that would
be inconvenient to have in the source code.
In any case, what we usually do is write extended descriptions and
detailed explanations in the hand-written part, and quick function and
argument references in the inline comments. It seems to work pretty
well.
(As an aside, the Gtk-doc process constructs and runs a program that
queries GTK+ objects about their signals and object argument types,
and generates the appropriate information in the template files for
you to fill in. I assume GOOPS could benefit from something similar.)
Federico