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

On 12/25/2010 8:40 PM, Yugui wrote:
> We need to discuss carefully and need an approval by ruby-core before
> changing RDoc into YARD.  Could you post your proposal as a feature
> request issue at the redmine?

Yes. If not tonight, I will write up a proposal and open a ticket on 
redmine by sometime tomorrow.

> I worry about difference between what Ruby API reference needs and
> what C API reference needs.  Doxygen comment describes how Ruby is
> implemented.

That's fine. They should certainly be different, and they certainly have 
different goals. The important part is that we come up with some 
standard formatting (and "documentation style") that can be applied 
globally, which will not only make documentation a lot easier to write, 
but easier to read as well. Right now there are a lot of semantic and 
stylistic inconsistencies in the docs that make room for lots of 
improvement-- and IMO most of that improvement can be achieved just by 
laying down a standardized style that is properly followed. That's the 
part I'm interested in. Given that YARD can cover both the C and Ruby 
ends of the spectrum, I think it's a good choice to move in that direction.

> A YARD doc for a method implementation will be good for C API doc too.
> But I don't hope description like class_alloc()'s appears in Ruby API
> documentation. How can we distinguish them?

YARD actually has an @api tag for distinguishing between API levels. You 
can have, say, a "ruby" API, and "C" API, though there's probably a 
better nomenclature for them. You can use queries (at the command line) 
to tell which items ("objects") should be generated in HTML (`yardoc 
--query '@api.text == "ruby"'`, for instance), making it extremely 
convenient for just this kind of thing.

- Loren