Re: [Chicken-users] Re: dbus:send bug

[John Gabriele]

On Wed, Mar 16, 2011 at 4:45 PM, Peter Bex <address@hidden> wrote:
> On Wed, Mar 16, 2011 at 04:52:45PM -0300, Stephen Eilert wrote:
>> > Almost all the "extracted" documentation I've seen is of shitty quality;
>> > people tend to use automatic extraction of docs as an excuse not to
>> > write proper documentation.
>>
>> As opposed to not writing it at all, or having it get out of sync with
>> the code, as they live in different places.
>
> That's an invalid argument; I've seen countless cases of inline docs
> which say one thing while the code *right below it* does something
> completely different.  When the docs are elsewhere, at least you
> won't be tempted to skim the comments and skip the code while reading
> the source.
>
>> Also, it is trivial to extract documentation for, say, an older egg
>> version. Which is in sync with the code, by default.
>> When you have documentation in the code, it goes wherever that code goes.
>
> That much is true.
>
> {snip}
>> One can make the argument that it would be *easier* to document the
>> code because you are looking at it, it is sitting right next to the
>> docs.
>
> You can also make the argument that you're being distracted by the way
> the code is laid out.  If you are documenting completely separately,
> you can think about the flow of text that makes most sense, grouping
> procedures that fit together logically. {snip}

A system that I think works pretty well is:

 1. separate standalone docs for things like overview, tutorial,
cheatsheet, cookbook
 2. API docs in the source code file (easily extracted), though, all
placed together at the end
 3. comments for low-level explanations of why something is done a certain way

For example, often in Perl 5:

  * (1) are put in separate .pod files,
  * (2) are put after a special marker at the end of the source code
(__END__) so the compiler can skip it
  * both (1) and (2) are accessed the same way using the `perldoc` command

---John