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

On Tue, Dec 28, 2010 at 05:52:13AM +0900, Ryan Davis wrote:
> 
> 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 ?

Sorry, I totally suck.  The example code should be this:

    class Foo
      # Converts the object into textual markup given a specific format.
      #
      # @param [Symbol] format the format type, `:text` or `:html`
      # @return [String] the object converted into the expected format.
      def to_format(format = :html)
        # format the object
      end
    end

I stole the example from the YARD docs:

  http://rubydoc.info/docs/yard/file/docs/GettingStarted.md

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