From: Jacob Fugal <lukfugl@...>
Date: 2006-06-16T08:28:04+09:00
Subject: Re: Is API documentation useless for learning?

On 6/15/06, Eric Armstrong <Eric.Armstrong@sun.com> wrote:
> Kindly ignore previous. The problem with frames.
> I was at the home page, not at the Element page.
>
> Observations:
>
>    1) Wow. Parent is a link. Who would have guessed?

True, this is something that might be made more obvious with a
different stylesheet. It's mostly a matter of taste and acclimation.

>    2) Visting that page, it looks familiar. As I
>       recall, I found it before by selecting "Parent"
>       in the class list.

Yes, that link will take you to the documentation for the parent
class, which in this case is REXML::Parent. It's not always (or even
usually) going to be a class named "Parent", though. That was just
coincidence in this case.

>    3) each, and to_a are indeed listed there--totally
>       without comments. I still have to visit the
>       source code to find out what they do. (Or
>       depend on the kindness of the folks who inhabit
>       this forum--which generates a lot of traffic.)

This a not the fault of API documentation as a concept, but of this
specific documentation. Those methods should be better documented. But
unwritten documentation is the bane of users no matter what
documentation style you choose.

>    4) Clicking on the file link shows me a page that
>       lists required files, and that's all.

Not sure about what is required to make this page show/link to the
full source, but I know I have seen it available (not for this
package, but others) before. Must be some rdoc setting. You'll notice
that the example you mention below of Builder doesn't have the source
here either, however.

> But here's a page that sets the bar for how API
> docs should read:
> http://builder.rubyforge.org/
>
> There are links to source code for each API. And
> clicking on the link displays the code inline.
> /Very/ nice. Anyone know how that was created?

It's just a setting on RDoc. In fact, if you look at the authoritative
documentation for REXML at
http://ruby-doc.org/stdlib/libdoc/rexml/rdoc/index.html, you'll see it
has this feature as well. The documentation you were looking at at
germane-software.com was built with an older rdoc and had a different
linking mechanism -- you clicked on the method name and it opens the
source in a popup. I too prefer the newer method, and if you look for
documentation on standard libraries at ruby-doc.org rather than
elsewhere, you'll have it available.

>    Seeing the method without any context turns out
>    not to help me very much. But it's way better
>    than nothing. For example, class! shows
>    _start_container, _css_block, and _unify_block,
>    none of which are in the method list!

They're not in the list because they're private/protected methods,
which aren't included in RDoc output by default, because they're not
part of the *public* API. You shouldn't need to know about them.

>    If had I seen that to_a returned the value of
>    "children" for example, I would still need to
>    know what that variable contains. Alternatively,
>    I need to search for occurrences of "children"
>    in the source code, in order to build up that
>    understanding. But that takes me back to the
>    need to examine source code, once again.

What this really comes down to is that you *shouldn't* need to
understand what the @children variable contains. You shouldn't need to
know where else it is used in the code. You shouldn't need to inspect
the source code at all; that link to the source of the method is only
a convenience for 1) if your curious, or 2) if the documenter failed
at his job.

In this case, the to_a method was poorly documented, you'll find that
a lot with any language and any documentation method.

> I don't /like/ coming to the conclusion that API
> documents have too many gaps to be useful, but I
> find myself being forced in that direction--and
> thinking about how to solve the problem.

It doesn't sound like your problem is actually with API docs in
general, but with the specific API docs for REXML itself. Like you
said, you like the Builder documentation -- it's also API
documentation built by RDoc.

The best thing any of us, you and me included, can do about this
situation is not to try to engineer a better solution than RDoc, but
to go in and *write documentation*. I've started with the webrick
library myself -- hopefully another couple months down the road I can
get it finished and added to ruby-doc.org.

Jacob Fugal