On Mon 11 Jan 2010 14:21, l...@gnu.org (Ludovic Courtès) writes: > Hello, > > Thien-Thi Nguyen <t...@gnuvola.org> writes: > >> There's lots of stuff in ice-9 that noone knows about, but I don't >> think there's something like this. Hopefully we can document more of >> it using the new (texinfo reflection) infrastructure. >> >> In reply to a similar comment from Ludovic, i offered to submit patches >> for missing (ice-9 foo) documentation. I hereby revise that offer to >> submit patches using this infrastructure, once i get around to playing >> with it. I imagine it can't be much different from Guile 1.4.x's. > > I’d prefer if it were used only for non-ice-9 modules. I really > sympathize with what the GCS says (info "(standards) Doc Strings and > Manuals"): > > Some programming systems, such as Emacs, provide a documentation > string for each function, command or variable. You may be tempted to > write a reference manual by compiling the documentation strings and > writing a little additional text to go around them--but you must not > do it. That approach is a fundamental mistake. The text of > well-written documentation strings will be entirely wrong for a > manual.
I agree with this, largely; but of course texi documentation has the disadvantage that it can (and does) grow out-of-sync with source. For small modules, a nicely written commentary plus an expository (i.e., in-order) layout of exported procedures, along with their docstrings, can get you 80% of the way there, very easily. And at least that way you know it's accurate. Also we could hack up other in-source documentary mechanisms that approach manual-style documentation more closely. For example a Manual block, like we now have Commentary. Andy -- http://wingolog.org/
