Re: rdtool and rdoc

At 12:14 PM -0500 7/22/02, Dave Thomas wrote:
>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
>
>    http://rdoc.sourceforge.net/doc/index.html
>
>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 http://kari.to/amrita/rdocs/ 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.

>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; [e-mail] 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