TomDoc - Reasonable Ruby Documentation

http://tom.preston-werner.com/2010/05/11/tomdoc-reasonable-ruby-documentation.html

by mojombo • 16 years ago

31 6 16 years ago

gcampbell2• 16 years ago

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)

davepeck• 16 years ago

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.

jackowayed• 16 years ago

>RDoc isn't just an abomination because of its approach -- it's an abomination because of its code.

Those are definitely not mutually exclusive.

jamesbritt• 16 years ago

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. )

gcampbell2• 16 years ago

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.

crazydiamond• 16 years ago

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.

TomDoc - Reasonable Ruby Documentation

Related Stories