ts <decoux@moulon.inra.fr> writes:
So... A suggestion. I'd like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself.^^^^^^^^^^^^^^^^
Not a good idea, for me.
Could you elaborate?
This is just useless and can just add confusion.
Guy Decoux
In the for what its worth department…
I’ve experimented on both sides of this issue, more in java than ruby
thus far, Prior releases http://virtualschool.edu/jwaa package used
doxygen (rdoc on steroids) to build truly impressive html dox from
inline comments, complete with graphical diagrams.
However I soon discovered that (1) generated documents lack a place
for conceptual overviews needed for learning a package from scratch,
(2) they weren’t useful during development compared to direct source
access ala vim/ctags, (4) including documentation in the source code
interfered with the code (5) the more doxygen struggled to create
useful documentation the larger the generated files were.
When the generated dox started dominating the download size, I
switched to a technique that I think works much better (unproven
assertion).
The http://virtualschool.edu/jwaa website provides copious narrative
tutorials but no detailed reference documentation at all. Instead the
tutorials provide hotlinks to a source browser for accessing source
code for a demo that demonstrates each point being discussed.
At 12:59 AM +0900 7/23/02, Dave Thomas wrote:
Paul Brannan pbrannan@atdesk.com writes:
How does RDoc handle multiple languages, though? I think for your
suggestion to work, it would have to make sure that there are at
least english and japanese docs. As Ruby grows, documenation in
more and more languages would be wanted. If you stick with inline
documentation, then eventually you will end up with more
documentation than code.True enough. There’s been some talk about having a --lang switch that
would select from available languages in the documentation, but as you
say that ends up making the files pretty messy.I’d suggest that in any scheme there’d be a compromise: the in-source
documentation would be in a single language. hen there’s be narrative
files in different languages: README.en, README.jp, etc. Both RDTool
and RDoc can do this well (although I believe RDoc to have the
advantage in inline documentation). Also, not being able to write
Japanese, I’ve never had RDoc processing a multi-byte character set
file, so there may well be things that need looking at.Cheers
Dave
–
Brad Cox, PhD; bcox@virtualschool.edu 703 361 4751
o For industrial age goods there were checks and credit cards.
For everything else there is http://virtualschool.edu/mybank
o Java Web Application Architecture: http://virtualschool.edu/jwaa
o Ruby Interactive Learning Environment http://virtualschool.edu/ile
Brad Cox <bcox@virtualschool.edu> writes:
However I soon discovered that (1) generated documents lack a place
for conceptual overviews needed for learning a package from scratch,
(2) they weren't useful during development compared to direct source
access ala vim/ctags, (4) including documentation in the source code
interfered with the code (5) the more doxygen struggled to create
useful documentation the larger the generated files were.
Brad:
Interesting points.
Of course both RD and RDoc support combinations of internal and
external documentation. RDoc also automatically hyperlinks between the
two. So you can write your conceptual stuff in RDoc in plain text
files, and then use the same RDoc markup inline for low-level code
documentation. Indeed, the RDoc distribution does this, with a
separate README file that can be read as plain text, or formatted into
the RDoc tree. RDoc also allows for source code browsing, with a
browser pane and the source for each method either inline or in
popups.
There's a (somewhat old) sample of RDoc at
if you click on simple_markup.rb, you'll even see an example of an
automatically generated diagram. (The current CVS tree produces even
nicer looking diagrams, thanks to Werner Neubauer)
You could also look at kari.to is available for purchase - Sedo.com for an example of
someone else's use of RDoc.
Anyway, I'm sure that no tool works for all purposes. You web site is
wonderful, and I'd never suggest using RDoc to generate it. But for
day-to-day code it seems to work pretty well.
Cheers
Dave
“ts” decoux@moulon.inra.fr wrote in message
news:200207221554.g6MFst919982@moulon.inra.fr…
ts decoux@moulon.inra.fr writes:
So… A suggestion. I’d like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself.^^^^^^^^^^^^^^^^Not a good idea, for me.
Could you elaborate?
This is just useless and can just add confusion.
Guy, are you against using RDoc to document the libraries and the
interpreter, or just against using it to document the interpreter? If the
latter, I would agree with you that for the most part RDoc might not be the
best way to document the interpreter’s internals. It could be useful for
documenting the built-in classes, however.
Of course both RD and RDoc support combinations of internal and
external documentation. RDoc also automatically hyperlinks between the
two. So you can write your conceptual stuff in RDoc in plain text
files, and then use the same RDoc markup inline for low-level code
documentation. Indeed, the RDoc distribution does this, with a
separate README file that can be read as plain text, or formatted into
the RDoc tree. RDoc also allows for source code browsing, with a
browser pane and the source for each method either inline or in
popups.
I know... http://virtualschool.edu/ile uses RDOC (http://virtualschool.edu/ile/tut/Pages/References/ILEReferences/index.html\).
But I may reconsider when I get more feedback on the still-experimental source browser approach. See http://virtualschool.edu/demo/JwaaQuickStart for a sample tutorial and http://virtualschool.edu/jwaa/demo/JwaaBrowse for the browser itself.
My comments were more based on observing my own needs when trying to absorb an unfamiliar package. I just don't find jakarta JavaDox useful at all, neither when starting out nor as reference material thereafter.
Most jakarta projects come with (typically poorly written) quickstart quide, but that's invariably where I turn first because in spite of their inadequacies, they are written from the new user's point of view.
The tutotorials come with a few cryptic samples/demos, which I found useful as cut/paste materials when just starting out. And they come with source code which I use for detailed nuts and bolts because that way its integrated with the editor (via ctags), not the browser.
The source browser notion emerged from trying to improve on the jakarta approach. The tutorial stuff is in the browser, and the source browser is integrated with that so that the tutorial can hotlink to source examples, with plenty of internal hotlinks so the user can browse around.
But unless you click a special link here's everything link (Source), you are never confused by being presented links to everything (a problem with rdoc). The tutorials only provide hotlinks to the specific file being discussed in the tutorial paragraph.
Another benefit is that source browser panes are generated dynamically and don't impose the space overhead of rdoc/doxygen. Although I thought doxygen's graphic diagrams were neat, I found I never really used them in practice, so they were just expensive flash and glitter.
Your mileage may vary of course.
There's a (somewhat old) sample of RDoc at
if you click on simple_markup.rb, you'll even see an example of an
automatically generated diagram. (The current CVS tree produces even
nicer looking diagrams, thanks to Werner Neubauer)You could also look at kari.to is available for purchase - Sedo.com for an example of
someone else's use of RDoc.
That's really nicely done! I'll model ILE's dox from that if I stay with rdoc for ILE.
At 12:14 PM -0500 7/22/02, Dave Thomas wrote:
Anyway, I'm sure that no tool works for all purposes. You web site is
wonderful, and I'd never suggest using RDoc to generate it. But for
day-to-day code it seems to work pretty well.Cheers
Dave
--
Brad Cox, PhD; bcox@virtualschool.edu 703 361 4751
o For industrial age goods there were checks and credit cards.
For everything else there is http://virtualschool.edu/mybank
o Java Web Application Architecture: http://virtualschool.edu/jwaa
o Ruby Interactive Learning Environment http://virtualschool.edu/ile
“Lyle Johnson” jlj@cfdrc.com writes:
Guy, are you against using RDoc to document the libraries and the
interpreter, or just against using it to document the interpreter?
If the latter, I would agree with you that for the most part RDoc
might not be the best way to document the interpreter’s
internals. It could be useful for documenting the built-in classes,
however.
One reason you might want to consider it is simply the ease of keeping
documentation up to date. For example, in imlib.c, there’s:
/*
* Returns a new Imlib2::Color::RgbaColor.
* Examples:
* r, g, b, a = 255, 0, 0, 255
* border = Imlib2::Color::RgbaColor.new r, g, b, a
*
* values = [255, 0, 0, 255]
* border = Imlib2::Color::RgbaColor.new values
*
*/
VALUE rgba_color_new(int argc, VALUE *argv, VALUE klass) {
Imlib_Color *color;
VALUE c_o;
color = malloc(sizeof(Imlib_Color));
memset(color, 0, sizeof(Imlib_Color));
c_o = Data_Wrap_Struct(klass, 0, free, color);
rb_obj_call_init(c_o, argc, argv);
return c_o;
}
…
rb_define_singleton_method(cRgbaColor, "new", rgba_color_new, -1);
That’s enough to et RDoc use the comment block as the documentation
for the class’ constructor.
Now say you decide to change the method. With the comment right there
next to the implementaton, it’s easy to remember to update it. If it’s
in a separate file, it’ll get left behind. Maybe… 
Cheers
Dave
"ts" <decoux@moulon.inra.fr> wrote in message
news:200207221554.g6MFst919982@moulon.inra.fr...
ts <decoux@moulon.inra.fr> writes:
So... A suggestion. I'd like to propose RDoc as the tool used to
document Ruby libraries and the Ruby interpreter itself.>> ^^^^^^^^^^^^^^^^
[...]
Like said
interpreter, or just against using it to document the interpreter?
this is the latter
Guy Decoux
You could also look at kari.to is available for purchase - Sedo.com for an example of
someone else’s use of RDoc.
Hi! I’m “someone else” using RDoc and I’m very pleased with it.
See kari.to is available for purchase - Sedo.com
I’m describing amrita’s features here. You can jump into API document
of referred classes. RDoc generates these links automatically. That’s
why I use RDoc for this document.
I think this is really nice for documents for programmers. And RDoc
has many more features like this.
Anyway, I’m sure that no tool works for all purposes. You web site is
wonderful, and I’d never suggest using RDoc to generate it. But for
day-to-day code it seems to work pretty well.
I agree with you.
I love RDTool too. The top page of amrita’s home page is written in RD
I have many Japanese home pages written in RD and my personal memo is
written in RD too.
I will continue to use both tools but I prefer RDoc for the document
that should be written in programmer’s view.
On Tue, Jul 23, 2002 at 02:14:09AM +0900, Dave Thomas wrote:
–
Taku Nakajima