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

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.

If we can add this support to RDoc, committers will not need to learn a
new format.  But if they choose to use the new syntax, Ruby
documentation that is output via YARD will have more functionality.

-- 
Aaron Patterson
http://tenderlovemaking.com/