TomDoc or Yard instead of Rdoc

[maasha]

The style-guide says:

Use RDoc and its conventions for API documentation.

However, the lack of consistent structure and readability in RDoc have lead to the specification of TomDoc. The style-guide should perhaps encourage TomDoc (optional)?

Here is some relevant reading:

http://tom.preston-werner.com/2010/05/11/tomdoc-reasonable-ruby-documentation.html http://gnuu.org/2010/05/12/whats-missing-from-tomdoc/ http://tomdoc.org/

[bbatsov]

Or we can just remove this. I don't think many people use TomDoc these days. Yard is pretty popular, though.

[sfcgeorge]

• (possibly biassed) blog post from creator of YARD on TomDoc's shortcomings: http://gnuu.org/2010/05/12/whats-missing-from-tomdoc/
• YARD has a nicer syntax than RDoc that will be familiar to developers coming from other languages. It is actively developed too unlike TomDoc.
• There is actually a TomDoc plugin for YARD, for best of both worlds.
• YARD powers rubydoc.info which automatically documents github projects and gems.

So my vote is changing to say YARD.

[Ch4s3]

+1 for YARD

[philoserf]

• for YARD

My unscientific examination of the community repos show very little Tomdoc in the wild and much Yard.

[snowe2010]

+1 for YARD, TomDoc is a very one sided view for documentation. Yard is a much better choice.

[onebree]

+1 for YARD. I only heard about TomDoc toady, when browsing Github's internal style guides. I see YARD almost always in the wild.

I agree with @bbatsov in that it should just be removed.

[arbox]

I would encourage people to use YARD.

[lazybios]

same as @onebree just see TomDoc in Github internal style guides. +1 for YARD

[bbatsov]

PRs welcome. :-)