[ruby-core:33910] [Ruby 1.9-Feature#4211][Open] Converting the Ruby and C API documentation to YARD syntax

Feature #4211: Converting the Ruby and C API documentation to YARD syntax
http://redmine.ruby-lang.org/issues/show/4211

Author: Loren Segal
Status: Open, Priority: Normal
Category: DOC

The Ruby (high level core/stdlib) documentation and its C API (low level) counterparts currently use two different formats (and tools) to write and generate the final docs. This creates a problem for committers and users alike, where:

 * Documentation is hard to write, because there is no single documentation style to follow (it depends on the API), and the two existing syntaxes are very different.
 * Documentation is harder to read because the style and formatting differ due to the lack of consistent enforcement of a single style.
 * Documentation for the C API (specifically) is harder to find

Currently, Doxygen @tag style syntax is slowly being introduced to improve the documentation of Ruby's C API, but this does not solve the three issues noted above. I propose to unify the documentation style used in the codebase to a single format (originally on ruby-core:33883[1]) by using YARD[2] syntax, which is very much like the Doxygen @tag style syntax being introduced anyway. Switching to YARD introduces a number of benefits, namely:

 * There would be a single syntax to learn for committers wishing to document code, making it easier to write,
 * The documentation would be formatted and styled consistently across both APIs for users to read,
 * Documentation would be generated by a single tool for both APIs, meaning a simpler workflow for documenters and users wishing to generate the docs themselves.

I pointed out in the original mailing list that much of the documentation problems come from a lack of unified styling, causing parts of documentation to be (or become) inaccurate due to a variety of "human-error" type issues, and because there are no tools to check the correctness. I believe switching to a unified style and making sure it is used consistently will solve many of those issues even without tooling, because it is easier to manually check for errors with a consistent formatting. Furthermore, using a consistent style allows us to take advantage of our tooling to check basic correctness (or "lint") the docs for simple errors. YARD already has tools to do this kind of thing (and they are easily improved), but they depend on that consistent syntax.

As far as the C API goes, there is little difference in the existing doxygen syntax (except that I'd suggest the '@tag' instead of Doxygen's alternative '\tag' prefixes, for compatibility). As I wrote in the above ruby-core thread, YARD can already handle most of the written doxygen documentation. Granted, a lot of the support for actually *generating* documentation for a straight "C" style API is missing in YARD, but as I mentioned, I would be willing to improve this support if there is a willingness by the ruby-core developers to create a unified documentation style.

h3. Steps forward:

We should first discuss whether the Ruby core developers are in favor of such a change. In the event that they are, we would have to look at a few things:

 * Maintaining compatibility with RDoc (or adding YARD's @tag style support to RDoc) for the high level Ruby API docs while converting the syntax. I have a few ideas on how this can be done.
 * Improving YARD's ability to generate HTML for straight "C" codebases (which I can implement, if we get this far)
 * Any other issues / reservations raised by the Ruby core team

This is certainly a large proposal, and has some compatibility snags (with RDoc, for instance). Regardless, I think these issues can be worked around or dealt with for the most part, and the benefits of much improved documentation, which Ruby really needs, are certainly worth the effort.

[1]: ruby-core:33883: http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/33884
[2]: YARD: http://yardoc.org


----------------------------------------
http://redmine.ruby-lang.org