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.
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...
I come from the Java world where each package (module) is documented
via:
(1)
javadoc comments in the source code giving the API-level documentation,
and
(2)
"package.html" files associated with each package describing the general
purpose and usage overview of that package.
If you download the source for a java package, you can build the docs
from the downloaded source (which includes the package.html files).
If you download an archive containing pre-compiled binary code, there is
always a separate archive containing pre-built docs.
Perl always has full documentation (both "API-level" and "overview
level") in the source code files, from which nice readable documentation
can be generated. And **all** the standard libraries are well
documented. I don't know about Python...
Is there any intention of providing a java-like or perl-like approach to
documentation for Ruby's libraries? 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....
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.
However I do not believe that writing "magazine articles" and having
them published in places unrelated to the original source code is the
solution. 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.
I don't mean to create trouble :-). I really loved Ruby by the third
chapter of "Programming Ruby: The Pragmatic Guide", and appreciate all
the work that has gone into it (including all the RAA and RubyForge
projects). However as a new user, the problems of *learning* ruby are
maybe more apparent to me than to regular Ruby users.
Any comments?
Regards,
Simon
> There's a documentation on shell.rb here, though it's very basic:
>
> http://kansai.anesth.or.jp/gijutu/ruby/man-z1/refm0329.html
>
> I believe this has been produced from RD doc included in the shell
> distribution below.
> http://raa.ruby-lang.org/list.rhtml?name=shell
>
> Hope this helps,
>
> Takashi Sano
>
>
|
