This is the mail archive of the guile@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: Guile documentation (was Re: [RFD] Guile projects page)


Greg Harvey writes:

 > The main problem with extraction is, well, there isn't currently much
 > to extract. I think it's a pretty good idea (but then again, I tend
 > to put a lot of explanatory comments in anyway). The first thing
 > that'll probably be necessary is to group guile's source files into
 > logical units (all the files dealing with files, data structures,
 > etc...  though there's quite a bit of overlap in some places). I'll
 > try to take a look at this (though for the next little while I'm
 > going to be very slow at just about everything... quiting smoking is
 > a real distraction :'(... though a good excuse to play a bunch of
 > quake2 >:').

ok how about considering the inverse...  write good docs and then have
source code update to use those docs (extract source code docstrings
from the doc source file).  the process is simpler in this direction
because formatting cruft from docs can be removed rather than added.
this also encourages people to describe their interfaces before starting
to hack, an unpopular practice at this time...

thi