From: Aaron Patterson <aaron@...>
Date: 2010-12-28T08:10:14+09:00
Subject: [ruby-core:33943] Re: [Ruby 1.9-Feature#4211] Converting the Ruby and C API documentation to YARD syntax


--NzB8fVQJ5HfG6fxh
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Tue, Dec 28, 2010 at 05:52:13AM +0900, Ryan Davis wrote:
>=20
> On Dec 27, 2010, at 12:20 , Aaron Patterson wrote:
>=20
> > On Mon, Dec 27, 2010 at 12:01:00PM +0900, Yui NARUSE wrote:
> >> Issue #4211 has been updated by Yui NARUSE.
> >>=20
> >> Your proposal is interesting, but as a lazy comitter, I want to know w=
hat we must do for this change.
> >> For example:
> >> * Committers must learn YARD syntax (what we should read?)
> >=20
> >  http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
> >=20
> >> * convert existing documents (who will do?)
> >> * fix some tools
> >> * fix build process
> >=20
> > I think if we do this correctly, conversion may be done slowly without
> > modifications of our tools.
> >=20
> >> I also want each vision for current use cases, like bin/rdoc and bin/r=
i.
> >>=20
> >> After all work is calculated and it is reasonable, I won't object the =
migration.
> >=20
> > I spoke with Loren about this issue on IRC.  I think we can accomplish
> > his goals by adding @tag support to RDoc.
> >=20
> > 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".
> >=20
> > Currently, RDoc will ignore @tags in your documentation.  For example,
> > this code:
> >=20
> >    class Foo
> >      # Converts the object into textual markup given a specific `format=
`=20
> >      # (defaults to `:html`)
> >      #
> >      # =3D=3D Parameters:
> >      # format::
> >      #   A Symbol declaring the format to convert the object to. This=
=20
> >      #   can be `:text` or `:html`.
> >      #
> >      # =3D=3D Returns:
> >      # A string representing the object in a specified
> >      # format.
> >      #
> >      def to_format(format =3D :html)
> >        # format the object
> >      end
> >    end
> >=20
> > Will produce an HTML document that looks like this:
> >=20
> >  http://skitch.com/aaron.patterson/rgsq5/class-foo
> >=20
> > RDoc doesn't crash or anything, but the output looks bad.
>=20
> ??? 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 =3D :html)
        # format the object
      end
    end

I stole the example from the YARD docs:

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

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

--NzB8fVQJ5HfG6fxh
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (Darwin)

iQEcBAEBAgAGBQJNGRzIAAoJEJUxcLy0/6/GyXQH/iKjskaCSpKF5S4rOeWm6Iwg
QH//13DKDWQg3ZxysLNz95Your3qY0VZ/1yN13qwfSU61uYPcPdJSOVCGujJC1A2
6UywPzkiptnozDLMf6gt757SSpzriNYXXIDLotWAYxqk6cGKPOc8e5JSeNU1tQcI
gdxDfnqNTMnRGC1UZKx1tKnY1xHigQ7GTGnrQANE/cGWDOqb+fNXs1kt4/6CNL4q
RYFiBG39kT3ElySb5sTWL4V61y0+OjBL5faGlY1o/mmGbu0KOg4ARTJDk+mQvT0s
k+6X1zJeaDMGxMbIR7LQWpANlJp6u9Of7UMkEVsZ5u2BGiBRCbQE3nIRirutEdg=
=+8+E
-----END PGP SIGNATURE-----

--NzB8fVQJ5HfG6fxh--