From: Loren Segal <lsegal@...>
Date: 2010-12-28T09:54:11+09:00
Subject: [ruby-core:33946] Re: [Ruby 1.9-Feature#4211] Converting the Ruby and C API documentation to YARD syntax


--Apple-Mail-1--489679043
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii


On 12/26/2010 10:01 PM, Yui NARUSE wrote:
>=20
> Issue #4211 has been updated by Yui NARUSE.
>=20
>=20
> 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://yardoc.org has guides among the one linked by Aaron. The "Getting =
Started" guide is a good place to look at, though.

> * convert existing documents (who will do?)

I'd certainly be interested in helping convert the existing =
documentation over to the new format. Some (not exactly sure how much) =
conversion can be done automatically, getting us part of the way there. =
A few manual conversions can be done afterwards to improve the overall =
quality. After an initial conversion, the tooling YARD has built-in can =
certainly help to narrow down what documentation needs work.

> * fix some tools
> * fix build process

YARD (the tool) could help here to add some sanity checks to the build =
process and ensure that new additions are well documented. Of course, =
the process would mostly be derived around a formulated documentation =
style, which I think should be the first step before starting to move =
things around. Discussing things like how to format return information, =
what style of language should be used, minimum requirements about =
documenting parameters, type information, etc.. Once these guidelines =
are set, we have something concrete to work with, and it should be =
fairly easy to apply these rules to start improving docs. I have =
suggestions about optimal ways to do things here too.

> I also want each vision for current use cases, like bin/rdoc and =
bin/ri.

Ultimately, it would be great for RDoc to begin to support the @tag =
syntax used to document the Ruby end of the documentation. If this is =
done, we can have the same RDoc support in Ruby and have it continue to =
document the Ruby side of things and stay in core, while YARD can be =
used to generate docs for both APIs for those interested in such =
generation and tooling support.

- Loren=20



--Apple-Mail-1--489679043
Content-Transfer-Encoding: 7bit
Content-Type: text/html;
	charset=us-ascii

<html><head>
    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
  </head><body text="#000000" bgcolor="#ffffff" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">
    <br>
    On 12/26/2010 10:01 PM, Yui NARUSE wrote:
    <blockquote cite="mid:4d18016a83880_3340aa72cfe5655@redmine.ruby-lang.org" type="cite">
      <pre wrap="">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?)
</pre>
    </blockquote>
    <br>
    <a class="moz-txt-link-freetext" href="http://yardoc.org">http://yardoc.org</a> has guides among the one linked by Aaron. The
    "Getting Started" guide is a good place to look at, though.<br>
    <br>
    <blockquote cite="mid:4d18016a83880_3340aa72cfe5655@redmine.ruby-lang.org" type="cite">
      <pre wrap="">* convert existing documents (who will do?)
</pre>
    </blockquote>
    <br>
    I'd certainly be interested in helping convert the existing
    documentation over to the new format. Some (not exactly sure how much) conversion can be
    done automatically, getting us part of the way there. A few manual
    conversions can be done afterwards to improve the overall quality. After an initial conversion, the tooling YARD has built-in can certainly help to narrow down what
    documentation needs work.<br>
    <br>
    <blockquote cite="mid:4d18016a83880_3340aa72cfe5655@redmine.ruby-lang.org" type="cite">
      <pre wrap="">* fix some tools
* fix build process
</pre>
    </blockquote>
    <br>YARD (the tool) could help here to add some sanity checks to
    the build process and ensure that new additions are well documented. Of course, the process would mostly be derived around a formulated documentation style, which I think should be the first step before starting to move things around. Discussing things like how to format return information, what style of language should be used, minimum requirements about documenting parameters, type information, etc.. Once these guidelines are set, we have something concrete to work with, and it should be fairly easy to apply these rules to start improving docs. I have suggestions about optimal ways to do things here too.<br>
    <br>
    <blockquote cite="mid:4d18016a83880_3340aa72cfe5655@redmine.ruby-lang.org" type="cite">
      <pre wrap="">I also want each vision for current use cases, like bin/rdoc and bin/ri.</pre>
    </blockquote><br>
  

<div>Ultimately, it would be great for RDoc to begin to support the @tag syntax used to document the Ruby end of the documentation.<font class="Apple-style-span" size="3"><span class="Apple-style-span" style="font-size: 13px; ">&nbsp;If this is done, we can have the same RDoc support in Ruby and have it continue to document the Ruby side of things and stay in core, while YARD can be used to generate docs for both APIs for those interested in such generation and tooling support.</span></font></div><div><span class="Apple-style-span" style="font-size: 13px; "><br></span></div><div><span class="Apple-style-span" style="font-size: 13px; ">- Loren&nbsp;</span></div><div><br></div><div><br></div></body></html>
--Apple-Mail-1--489679043--