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

On Dec 27, 2010, at 12:20 , Aaron Patterson wrote:

> On Mon, Dec 27, 2010 at 12:01:00PM +0900, 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://rubydoc.info/docs/yard/file/docs/GettingStarted.md
> 
>> * convert existing documents (who will do?)
>> * fix some tools
>> * fix build process
> 
> I think if we do this correctly, conversion may be done slowly without
> modifications of our tools.
> 
>> I also want each vision for current use cases, like bin/rdoc and bin/ri.
>> 
>> After all work is calculated and it is reasonable, I won't object the migration.
> 
> I spoke with Loren about this issue on IRC.  I think we can accomplish
> his goals by adding @tag support to RDoc.
> 
> Adding @tag support to RDoc would allow us to unify Doxygen and RDoc
> documentation formats.  But this means we must define the meaning of
> "@tag support".
> 
> Currently, RDoc will ignore @tags in your documentation.  For example,
> this code:
> 
>    class Foo
>      # Converts the object into textual markup given a specific `format` 
>      # (defaults to `:html`)
>      #
>      # == Parameters:
>      # format::
>      #   A Symbol declaring the format to convert the object to. This 
>      #   can be `:text` or `:html`.
>      #
>      # == Returns:
>      # A string representing the object in a specified
>      # format.
>      #
>      def to_format(format = :html)
>        # format the object
>      end
>    end
> 
> Will produce an HTML document that looks like this:
> 
>  http://skitch.com/aaron.patterson/rgsq5/class-foo
> 
> RDoc doesn't crash or anything, but the output looks bad.

??? How does the above rdoc output @params ?