
TomDoc - Reasonable Ruby Documentation - mojombo
http://tom.preston-werner.com/2010/05/11/tomdoc-reasonable-ruby-documentation.html
======
davepeck
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
_> RDoc isn't just an abomination because of its approach -- it's an
abomination because of its code._

Those are definitely not mutually exclusive.

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

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

~~~
gcampbell
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
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.

