From: Brad Cox Date: 2002-07-23T02:02:29+09:00 Subject: Re: rdtool and rdoc 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 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