TomDoc: Reasonable Ruby Documentation
TomDoc is a new code documentation format that I’ve been using for the last several years. I’ve finally formalized it and we’ve started using it for all projects here at GitHub. Code documentation with TomDoc looks nice in plain text and encourages specification of all parameter and return types without getting too strict about it. I wrote a post on my blog and you can see the full spec at tomdoc.org.
Comments
This is very interesting. I think it has been clear to many of us that Ruby’s documentation system has been in sore need of the “next big innovation” for some time.
So I am glad to read someone has been working on it for such a long time! Reading over the specification, it looks pretty good. I do have some a couple of points and questions to raise though. I will start with the simplest of issues and progress to the more complex
1) The spec says, “There MUST NOT be a blank line between the comment block and the method definition.” MUST? I think that seems a bit harsh for something so minor. Surely the parser can handle at least one blank line, should a developer prefer it that way.
2) Does TomDoc support any markup at all? Bold, italic, hyperlinks, etc? While I fully understand the goal of readable plan text, at the same time we want to produce even nicer production output. There must be a reasonable middle ground.
3) You attr_writer docs are a bit annoying. 5 lines per writer? Really? Side note: I have always wanted to be able to document attributes via comments on their right side –though maybe that’s asking too much.
4) What about meta-programming. Is there any way to specify a custom attribute or method defined via dynamic means?
5) And what about ri? Does TomDoc provide anything along these lines, or are we still using rdoc for that?
Lastly let me say, good work. Code docs are a tough nut and I am glad to see new innovation efforts into the problem. You Public interface idea seems especially promising.
Post a comment