[ruby-core:33884] Re: Getting involved in Ruby

Might be a bit of a sidestep from the original discussion, but:

On 12/25/2010 7:24 PM, Yugui wrote:
> I introduced document generation by Doxygen (www.doxygen.org). Ruby
> 1.9.2 or later generates documentation of C API on its build.
> BUT, there are a few doxygen comment in Ruby. It means there are many
> tasks to do.  You can see some documentation examples in class.c and
> object.c.

If we are going to be accepting Doxygen-style @tag based comments, why 
not just start switching over to YARD syntax for both the C API and Ruby 
documentations? YARD uses the same @tag style syntax that doxygen does, 
so we would end up with a consistent documentation format across both 
the C API and Ruby docs. That sounds like a big win to me. Currently we 
use RDoc syntax for one part of documentation, and (are starting?) to 
use a completely different syntax for the C API. That's messy and much 
harder to maintain.

FWIW, after looking at the class.c, YARD can actually already handle 
most of the written doxygen-style docstrings, and in fact implements 
many of the tags used (@note, @return, @param, etc.). I'd be interested 
in extending support for YARD to better cover the lower level C side of 
the Ruby API, if there was willingness from the Ruby devs to commit to a 
single syntax for documentation.

Regards,

Loren