TomDoc - Reasonable Ruby Documentation(tom.preston-werner.com)
tom.preston-werner.com
TomDoc - Reasonable Ruby Documentation
http://tom.preston-werner.com/2010/05/11/tomdoc-reasonable-ruby-documentation.html
6 comments
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.
>RDoc isn't just an abomination because of its approach -- it's an abomination because of its code.
Those are definitely not mutually exclusive.
Those are definitely not mutually exclusive.
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)
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. )
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.
I've been using yard for a while. Although, i often forget the tags and their usage, but one can use snippets for that (snipMate.vim) for example.
One can also write a script to generate the tags for a method.
One can also write a script to generate the tags for a method.