From: Loren Segal Date: 2010-12-26T11:20:06+09:00 Subject: [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