Gavin Sinclair wrote:
[...]
We definitely more complete docs on lots of things though, that is my
main problem with Ruby. There are lots of things I know I can do,
without duplicating work, but since I can't find docs on it, it's
difficult to do. The push for RDoc is great, but I still have the same
complaints about it that I have of Javadoc, it generally doesn't give
some sort of example for each function, class in the library. I learn
far more from an example of code use that encompasses a wide part of the
library then a list of functions I can call in the library. The 2nd is
great, but it only works if you know how to use it already. Fix the
documentation and I think ruby will certainly spring ahead.
I fully agree on all counts. I'll just mention, though, that RDoc
actually encourages introductory/usage/example documentation, *so long as
the developer wants to write it*. For example:
I wasn't really trying to criticise RDoc or even Javadoc as a method of
documentation, I was trying to point out that they are oft misused.
Many times the developer decides against writing examples, and instead
just lightly explains each function.
I think the problem with class/library documentation in RDoc or Javadoc
style, is that it's harder when you first dive in to get a coherent
picture of how the library interacts. And that's the key component to a
library, knowing what it does and how to do it. Functions tell how to
set and check state, and generally how to start things and whatnot but
it doesn't describe the core philosophy of how the library works. It's
often very difficult to determine that from documentation that focuses
on each function/field, and not on the grand scope of the library.
Unless each function/field shows a good example on how to use it in the
total context of the library. It would be nice to have a tutorial in
each library to get your feet wet, and while it's certainly there in
some, it's missing in lots, or difficult to find.
There are certainly excellent examples of documentation in this format
which do a good job of describing exactly what I want above, but there
are many examples where it feels like the documentation is a couple
remarks strewn throughout the source. In that case I prolly will get
more from reading the source then looking at the rdoc.
Sorry, I certainly think it's great that we have what we have, but I
still feel like we can go alot further.
*
http://extensions.rubyforge.org/
The *first thing you see* (an important consideration for people looking
at an RDoc screen for the first time) is a description of the project,
installation, usage, technical information, links, etc.
*
http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/index.html
Here, the first thing you see is a brief description of the 'pathname'
Ruby standard library. It could use a one-paragraph description and usage
example to help the casual browser (person, not software) decide whether
they're interested. However, the most important thing is the prominent
"For documentation, see class Pathname [linked]", which contains intro,
examples, and a method catalogue.
That's the style I like, particularly if the method catalogue shows how
each function is used in an example.
RDoc was certainly not a hinderance to creating decent documentation for
the 'pathname' library!
Sorry didn't mean to say it was a hinderance, just that perhaps not all
were as diligent in writing documentation for there libraries as they
could be.
They say a picture is worth a thousand words, well I say a nicely
commented example that illustrates how the library is supposed to
interact is worth the same as all the single function documentation that
can be thrown at me.
Many thanks to all who have documented, and also to all those who have
written libraries, I guess I just get frustrated when I find a library
that does what I need, but I don't know how to use it.
Charlie
I think a manual submission process is suitable, with