RDoc isn't just an abomination because of its approach -- it's an abomination because of its code. I'm in the middle of a project that requires making RDoc do things that other more modular systems would have little problem with... but to solve the problem I ended up private forking the entire RDoc codebase.
I like it - I've also had your experience with the other Ruby documentation formats (RDoc can become too messy, YARD too many @tags). One potential suggestion:
It might be worth adding some indication of how to specify a duck-type (rather than a Class) in the arguments section. (i.e. "name - The name of the object; should respond to to_s", or hopefully something less clunky than that)
I've become fond of Yard (http://yardoc.org/), especially after speaking with Loren Segal at MountainWest RubyConf in March. I'm planning on moving ruby-doc.org over to yard when I can make sufficient time.
You can debate whether a doc tool is too clunky or has too many options or too many @tags, but in practice the biggest issue with docs is the lack of them. I don't really see Yet Another Doc Format changing that.
Yard is nicely done, in active use, and works nicely with Disqus for user comments. I feel comfortable poking around the code, and know I can get support form the developers and community. This may also be true for Tomdoc, but I'm more reluctant to go for a newer format and code base.
(Side rant: One thing that would really get my attention in a doc tool would be parsing usage of attr_* and documenting the results as the methods the are, and not as Java-ish virtual attributes. )
I hadn't looked at Yard in a while, actually, but http://yardoc.org/docs/ruby-core is a pretty compelling example of some nice output, especially given that it's generated from the C code.
[+] [-] davepeck|16 years ago|reply
[+] [-] jackowayed|16 years ago|reply
Those are definitely not mutually exclusive.
[+] [-] gcampbell|16 years ago|reply
It might be worth adding some indication of how to specify a duck-type (rather than a Class) in the arguments section. (i.e. "name - The name of the object; should respond to to_s", or hopefully something less clunky than that)
[+] [-] jamesbritt|16 years ago|reply
You can debate whether a doc tool is too clunky or has too many options or too many @tags, but in practice the biggest issue with docs is the lack of them. I don't really see Yet Another Doc Format changing that.
Yard is nicely done, in active use, and works nicely with Disqus for user comments. I feel comfortable poking around the code, and know I can get support form the developers and community. This may also be true for Tomdoc, but I'm more reluctant to go for a newer format and code base.
(Side rant: One thing that would really get my attention in a doc tool would be parsing usage of attr_* and documenting the results as the methods the are, and not as Java-ish virtual attributes. )
[+] [-] gcampbell|16 years ago|reply
[+] [-] crazydiamond|16 years ago|reply
One can also write a script to generate the tags for a method.