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

[Stephen Eilert]

On Wed, Mar 16, 2011 at 3:34 PM, Peter Bex <address@hidden> wrote:
> On Wed, Mar 16, 2011 at 02:58:59PM -0300, Stephen Eilert wrote:
>> > Documentation for eggs is usually manually written.  As far as I know,
>> > nobody uses automatic extraction of comments from code.
>>
>> And that's a shame.
>
> Why?
>
> 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. 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.

>
> Also, writing documentation by hand forces one to think about writing
> it in a way that it can be read from beginning to end and have it make
> sense.

But that's usually done after the code has been written, as an afterthought.

> Having documentation on a wiki means people can add notes about and
> rewrite sections they found difficult or hard to understand, thereby
> increasing overall quality.

Notes can be added no matter how the documentation is generated. As
for rewriting sections, I agree with you - it is easier in a wiki. It
would be helpful to know how often that happens in practice, though.

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. If you are reading it in the source you can even spot the fact
that, say, a function's arguments are documented wrong, because you
can see it right there.


> Finally, when the inline documentation *is* done really well, you end
> up with a lot of documentation getting in the way when you're trying to
> read the code.

That is also true. See, for instance, ActiveRecord. It has benefits
too - you can see the documentation right next to the section you are
editing or trying to understand and breaks up code sections visually
(when done well).

I have stopped complaining about the lack of docstrings when
chicken-doc (and chickadee) was created. It is not an ideal solution
(from my point of view), but it mostly solves the problem of
retrieving the documentation for chicken and eggs in the repository.

However, I still think that it could be useful. If not for Core and
Eggs, then perhaps for our own Scheme projects. Maybe some hack using
Hyde?


--Stephen

Sent from my Emacs