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

On 12/26/2010 10:01 PM, Yui NARUSE wrote:
> 
> Issue #4211 has been updated by Yui NARUSE.
> 
> 
> Your proposal is interesting, but as a lazy comitter, I want to know what we must do for this change.
> For example:
> * Committers must learn YARD syntax (what we should read?)

http://yardoc.org has guides among the one linked by Aaron. The "Getting Started" guide is a good place to look at, though.

> * convert existing documents (who will do?)

I'd certainly be interested in helping convert the existing documentation over to the new format. Some (not exactly sure how much) conversion can be done automatically, getting us part of the way there. A few manual conversions can be done afterwards to improve the overall quality. After an initial conversion, the tooling YARD has built-in can certainly help to narrow down what documentation needs work.

> * fix some tools
> * fix build process

YARD (the tool) could help here to add some sanity checks to the build process and ensure that new additions are well documented. Of course, the process would mostly be derived around a formulated documentation style, which I think should be the first step before starting to move things around. Discussing things like how to format return information, what style of language should be used, minimum requirements about documenting parameters, type information, etc.. Once these guidelines are set, we have something concrete to work with, and it should be fairly easy to apply these rules to start improving docs. I have suggestions about optimal ways to do things here too.

> I also want each vision for current use cases, like bin/rdoc and bin/ri.

Ultimately, it would be great for RDoc to begin to support the @tag syntax used to document the Ruby end of the documentation. If this is done, we can have the same RDoc support in Ruby and have it continue to document the Ruby side of things and stay in core, while YARD can be used to generate docs for both APIs for those interested in such generation and tooling support.

- Loren