Dave Thomas wrote:
> The underlying philosophy of the RDoc markup is that it should be
> transparent... I wanted RDoc to be such that some third party reading the
> original source didn't know that the comments were in a format
> suitable for RDoc... As a result, RDoc contains lots of heuristics. If it gets it wrong
> every now and then, I personally think that's an OK tradeoff.

+1
I really enjoy this about RDoc.

Docs are primarily a tool for development.  Their first requirment is
to be accurate and up to date.  That only happens when they're trivial
to change.  If you need to spend time marking them up, you'll wait
until you've completed the project to do so.

To me, this is all about enabling Agile development, in line with
Ruby's philosophy.

I would add that to publish end user distributable API docs, a tool
that is about more formal and controlled, like javadoc, is warranted.
Alas, there are very few Ruby project that are mature enough to have
that problem...