This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Doc Tasks (was RE: docstrings in Guile!)


Federico Mena Quintero wrote:
> 
> >  As another data-point, people might want to take a look at Java's
> >  "javadoc" system.  You basically add special comments in the source.
> >  These are extracted by the javadoc program, which generates quite
> >  decent on-line documentations.
> 
> For the record, we are using a similar system for the GNOME Project.
> This is the gtk-doc documentation system.  It extracts
> specially-formatted comments from the sources and builds SGML
> templates that can be edited further by hand.  Then it takes those
> templates and turns them into final SGML.  Changes in the source
> comments are non-destructive to the templates, you can regenerate them
> and the edited contents will be preserved.
> 
> This works pretty well for GNOME.  Guile may want to have something
> similar; it makes writing API reference documentation very easy, since
> it is always in sync with the source.
> 

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?

 - Maciej

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]