On Wednesday, October 8, 2003, at 10:04 PM, Simon Kitching wrote:
Hi Takashi,
Your documentation was exactly what I was looking for.
However, I am puzzled that I would need to go to RAA to get the docs.
History. As you note below, inline documentation and multibyte
character encoding don't work that well. A lot of Ruby documentation is
in Japanese.
I would have expected documentation on libraries included in a standard
Ruby distribution to be distributed *with* that version of ruby. Or at
least for there to be a single downloadable "docs" file that includes
documentation for every standard library...
This is what Gavin Sinclair - principally - is working on. See:
http://www.rubygarden.org/ruby?DocumentingTheStandardLibraries
I come from the Java world where each package (module) is documented
via:[snip]
Perl always has full documentation (both "API-level" and "overview
level") in the source code files, from which nice readable
documentation
can be generated.
[snip]
We're working on it and would like your help.
Is there any intention of providing a java-like or perl-like approach
to
documentation for Ruby's libraries?
Yes. Much of the discussion has been on this list and most of the
impetus for the effort has come from Gavin Sinclair. I know that your
views, input and help would be appreciated.
I understand that things are a bit
trickier when docs need to be generated in multiple languages, and that
therefore at least some of the documentation needs to be outside the
source code file. Maybe some tools then need to be created to make it
easy to know when documentation "external" to the source code file has
become out-of-date with respect to that source code....
I think documentation should indicate date of writing, Ruby version and
application or library version.
As I said in my original email, I am happy to help out. This would
include writing documentation, and writing/testing tools for supporting
multi-language documentation.
Great. I personally think the primary need is for more documentation
and less for documentation tools, but documentation tools for
multi-language documentation would no doubt be helpful.
However I do not believe that writing "magazine articles" and having
them published in places unrelated to the original source code is the
solution.
I hope that you will write magazine-style articles because they can
help people use even well-documented APIs and offer extended examples
of usage. There is no limitation on where a magazine-style article can
go (e.g., a Ruby documentation website, RAA, RubyGarden Wiki, CVS
repository, included with distribution if developer wants to,
RubyForge, etc. or all of the above).
How is the next user of Shell going to find that info? Having
documentation for standard Ruby libraries available only on a
per-module
basis via an RAA entry doesn't seem particularly user-friendly either.
Documentation needs to be easily available, checked in to the same CVS
repositories as the source code, and be updated when the code is
updated.
This is what Gavin Sinclair has been working on with the RDoc project.
Once the documentation is written, there is no limit on where it can go.
[snip]
as a new user, the problems of *learning* ruby are
maybe more apparent to me than to regular Ruby users.
A multitude of learning resources of high quality will help, but they
don't yet exist. So we need your help creating them.
[snip]
Regards,
Mark
| 
