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

[Peter Bex]

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.

> > 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.

Yeah, just like inline docs.  With inline docs it's worse; witness the
countless ruby libraries where you think you get docs for a method
because it's listed in the index, only to find an empty line staring
at you when you click it.  Utterly frustrating, that!

If it isn't documented and it won't show up in the docs, at least you
won't start wondering whether it's intended to be part of the
"official API" or it will be gone in the next version, and if you're
even using it as intended.

> > 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.

It does happen.  Not super-often though.  You can look through the logs
if you want concrete numbers.  Most are simple fixes of spelling mistakes
or markup fixes, to be sure, but you can also be sure those wouldn't be
done when it would require making a patch and submitting that to the
author!

> 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.  Sometimes code is organised
in one way because that's more convenient or logical when defining
similar procedures together, but it makes more sense to document them
for a newbie.  For example, you can have the docs talk about a
"low-level" API and a high-level API, while you group the code together
so that low-level procedure A1, A2 and A3 are followed immediately by
the high-level procedure A that combines the three in a smart way.

> 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.

Generally when documenting the procedures you're not doing it straight
from memory; you have another buffer with the source open which you
consult occasionally.

> > 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.

Ah, Rails.  The perfect example of what I hate about inline docs.
Those classes are prefaced with pages upon pages of text, and you can't
easily find the code.  Also, the code is very hairy and convoluted, but
all the text obscures that fact.  Besides, the Rails docs are one of the
worst ones.

All the text is grouped together because that makes most sense in the
documentation tool, and then you get lots of scantily-documented methods.
When you click in the index on a method to find the docs, you basically
get almost nothing.  You're expected to "know" that you can scroll up
to find the actual documentation, or - worse - to know the right related
class you should click because that's where the real docs are.

See for example:
http://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html

A bit of docs for one method, the other ones have _zero_ documentation.
For example, what the *hell* does
"find_or_instantiator_by_attributes(match, attributes, *args)" do?
Nice that the code is right there, but it's so winding and convoluted
I sure can't find out what it does by skimming it.

If I'm not supposed to use it as an API end user, what is it doing in
the docs?

Another glorious example:
http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Column/Format.html

What's that used for?  My guess is it's some internal thing, but
who knows?

To stop picking on Rails, let's choose a different example.  I've had
the displeasure of trying to use the svn_client library.  It builds on
top of APR, which one would say is a rather low-level and supposed to be
a commonly used library, so you'd expect it's well-documented.

When you click the documentation link on the website, you're greeted with
this welcoming page:
http://apr.apache.org/docs/apr/1.4/

Then, you think "ah, I have seen this function call
apr_allocator_create(apr_allocator_t **allocator);
that's likely coming from <apr_allocator.h> and I'd like to know
what it does", so you click "files" and click "apr_allocator.h".
http://apr.apache.org/docs/apr/1.4/apr__allocator_8h.html

But there's nothing there.  You're expected to click once more,
and you're carried to some completely different file with no
context to figure out where you are.  Anyway, this is where it
goes:

http://apr.apache.org/docs/apr/1.4/group__apr__allocator.html#gf834f409a34b7f8656c045cff02fd953

This is another great example of why generated doctools guide people
into writing inanely stupid zero-content documentation:

"Create a new allocator"
Parameters:
        allocator       The allocator we have just created. 

I figured out that much just looking at the freaking call!
What I *really* want to know when I visit the documentation
page is what an allocator *is*, and what I can use it for.

Also, it doesn't mention what the hell it returns!  Yes,
some kind of status value, apparently.  So you click it,
and it takes you here:
http://apr.apache.org/docs/apr/1.4/group__apr__errno.html#gf76ee4543247e9fb3f3546203e590a6c

it says:
-----
typedef int apr_status_t

Type for specifying an error or status code. 
-----

Fantastic.  I already deduced that from its name.  What are the
values it can hold?

If you read on, you can guess that maybe you're not supposed
to use these codes immediately?  Maybe you should pass it to
apr_strerror()?  Who knows?  It certainly isn't *documented*.

The endless piles of HTML documentation in APR sure *looks*
like it's fully documentated, but a lot of it is just this
kind of stuff; repeating in English what the code says, but
not really adding the much-needed exposition to it which would
make the documentation actually *useful*.

I think using a documentation tool like this makes people feel
all warm and fuzzy.  It sure feels good to have all this documentation
generated for free, and to be prompted to write the documentation
because it's right in the code; but what it actually does is something
insidiously evil: it warps the way documentation is written to be
extremely oriented at the code rather than oriented at providing a
decent narrative which explains what things are for, rather than what
they do.  The code generally describes what it does better than any
text that's added, unless it's a particularly hairy piece of code.
(and in that case, it's customary to provide a short description
of the algorithm, even if not using inline docs)

> 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.

I suppose it's just a matter of taste.  I've just had too many bad
experiences with this kind of docs to have any faith in it.

> 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?

I won't stop you from doing it for your projects, but don't force
this on others.

PS: Sorry for the rant, but the Rails documentation really sets my blood
boiling.

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth