> And I feel much worse about this one because documentation is so important. 

Yes documentation is important, especially about teaching other people, 
or showing them how this is supposed to be used (and even better how it 
is designed and why, if there is enough space and time to do so, in a 
brief and concise manner) - but a documentation tool should not come 
into one's way to think and design in my humble opinion. The current way 
leaves some things to be desired with rdoc - one example I found 
peculiar is that a .rb file of rake had about 6 methods. And ALL methods 
had # :nodoc: assigned and exactly 0 lines of other docu. I think this 
is somewhat sub-optimal as solution to think about documentation this 
way, that the first line of thought is wrapped towards the tool rather 
than other people (but just to get it out too, i think having rdoc is a 
lot better than not having it)
-- 
Posted via http://www.ruby-forum.com/.