Re: rfc: (ice-9 accumulate)

[Andy Wingo]

On Mon 11 Jan 2010 14:21, address@hidden (Ludovic Courtès) writes:

> Hello,
>
> Thien-Thi Nguyen <address@hidden> 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/