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

On 12/28/2010 8:18 PM, Eric Hodel wrote:
> If we're building a documentation standard for ruby we'll need an example of good documentation, a "template" which we will enforce when documentation is submitted.

For the most part I agree. An example will help validate a proposed 
"template". jQuery and Cocoa's APIs are good, but I also know of a few 
Ruby libraries using (YARD's) @tag syntax if we're looking for something 
closer to home. Any suggestions from your end?

>>> I've read documentation generated by such tools many times and have always found them difficult to navigate as there is not enough context to understand the interaction between all the components of an API.
>> What does RDoc do better, here? Again, this is not the fault of @tag based syntaxes-- it is the fault of the tools. For instance, doxygen has some rough edges in displaying documentation, but this is the fault of the tool, not the use of @tags. Keep in mind that I'm not proposing a tool, just a *unified documentation style*. RDoc could certainly implement this if you think it does the best job at displaying information to a user.
> Good documentation is independent of the tools used to process it or the syntax used to write it.  I don't think a different tool can make better documentation without human intervention.  Some characteristics of good documentation are consistent wording, approachable writing, comprehensive coverage and useable examples.  I'm unsure of how a tool can help with anything other than comprehensive coverage.

You're right about human intervention. The tools are basically there to 
help you sift through the data, bringing to light problem areas based on 
heuristics. I don't think this functionality should be underestimated, 
though. With so much documentation to sift through, it's useful to have 
some way to do some quick sanity checks-- ultimately this will come down 
to good manual checking of the raised issues.

Good tools can be used to, for instance, test that the examples provided 
in the docs actually work. This is kind of hard with high level APIs 
that depend on some initial state, but with Ruby's core classes where 
you can write isolated examples, this would be extremely useful and 
effective. Both tools and syntax can also be used to ensure you're 
specifying the right type information in your documentation. Syntax also 
especially helps to ensure consistent wording across documentation, 
because you end up with less of it, which means less to manually review.

A few examples I commonly come across:

  - The common phrasing of "This method returns ...." becomes obsoleted 
by a single "@return ...". The wording of how "this method returns" is 
phrased, and *where* it can be found in the docstring is simplified so 
that it becomes really hard to screw up.
  - Having the tag there means you can also check for the existence of 
that information much more easily. In docs without such a consistent 
syntax, you couldn't just check for the existence "Returns", as it's not 
guaranteed to exist. See Array#transpose for the first example I came 
across. Thankfully in this case there is at least a simple working 
example that summarizes the information. That is not always the case.
  - Again, @return gives documentation a consistent form, and also gives 
users a consistent placement of that information. Misunderstanding 
Array#reject vs #reject! is a common "newbie mistake". Although 
#reject!'s documentation does say it returns nil, that information is 
often lost in the wording ("... but returns nil if..." is not exactly 
put front and center as it should be). A @tag based syntax would allow 
you to rewrite the #reject! method as:

     # Deletes all elements from _self_ for which the given block 
evaluates to +true+.
     # @yield [item] each item in the array
     # @return [Array] if at least one change was made
     # @return [nil] if nothing was changed

Having tags allows the tool to (more easily) display this information 
consistently and organize information for the reader by return type, 
rather than having the documentor arbitrarily decide the importance of a 
return type or general return information-- or having reviewers manually 
ensure that "return information is displayed at the ____ of a 
docstring". The organization of the data should be provided by the tool, 
which makes up a big part of the overall documentation quality. Using a 
tool that provides poor organizational flow can be just as bad as having 
poorly written documentation-- you pointed this out above, too.

  - I'll throw this in there: YARD uses a convention return type "void" 
(@return [void]), which denotes that although Ruby always returns "a 
value", the value being returned from the method is effectively 
"meaningless" and equivalent to void. There are a small batch of methods 
in the Ruby docs that have this kind of behaviour, but this happens a 
lot in higher level APIs. Usually people ignore making any mention of 
such a "meaningless" return value, but this causes ambiguity because now 
the reader doesn't know when this information was omitted due to 
"meaninglessness", or carelessness by the documentor. Checking that a 
@return tag exists make sure that there is never such an ambiguity. And 
this is definitely something that syntax can give you.

Approachable writing, of course, can't be corrected by a tool. That one 
needs proper manual review. I would certainly not mind volunteering some 
of my time for such reviews.

>> However, it's important to realize that supplying a "bare minimum" guideline to a documenter does a lot to improve the quality of documentation. Obviously, manual checks would have to be done to make sure people are not just "checking off boxes", but having those tags there lets us know what to look for when reviewing documentation, and lets *them* know what they should be writing. This is an improvement over the current adhoc "just-write-something" methodology. Tags also give us the ability to implement tooling later, because the docs are much more easily parse-able.
> A common feature of documentation in ruby core is to "tag" method parameters in ++,<tt></tt>  or</code></code>.  Matching the "tagged" items in a comment to the method's arguments is trivial way to implement an enhanced coverage report without requiring @tags.

I'm not sure I really see how this could be applied. The existence of a 
+parameter_name+ does not always imply that the quality is there. This 
is *also* true for a @param tag. On the flipside, the *lack* of a 
+parameter_name+ in the docs does *not* mean the argument was not 
documented. For instance, people often say "takes a string" instead of 
"takes string +str+", when there is only one argument (I think this is 
acceptable). However, if you enforce documentation for a parameter to be 
located inside a @param tag, you *can* guarantee that a missing @param 
tag means the parameter was not documented. You still end up with a few 
false negatives, where the parameter really needs no documentation, but 
these false negatives are a relative few to the non-tag alternative, IMO.

> One of the greatest joys I've found in programming is the ability to have the computer do work for me.  I would prefer to have a tool that could figure out what I haven't documented, or documented well enough, with the fewest possible concessions.

Certainly. I don't believe @tags are concessions, though. If anything, 
there is less superfluous writing when using tags, because you can rely 
on the tool to expand language for you in a consistent fashion. YARD 
actually takes advantage of this rule: when given a @return tag and no 
extra docstring ('docstring' meaning plain "English" text, not tag 
metadata), YARD expands this out to a full English sentence in the 
method summary for you. You can rewrite the awkward:

     # Returns a new string that is encoded using the ROT13 cipher
     # @return [String] the rot13 version of the string
     def rot13; ... end

Into a much more compact:

     # @return [String] a new string that is encoded using the ROT13 cipher
     def rot13; ... end

YARD handles the "Returns " for you in the summary, that is you still 
get the same plain English text as above, but also still organizes the 
return type information alongside the metadata below. I think there are 
a lot of places where tags can be leveraged in this way to make your 
life *easier*, not harder. This was certainly one of YARD's original 
design goals from the get-go. If I truly believed @tags were more 
cumbersome and less advantageous, I would not have used them.

>>> I question merging YARD into Ruby and replacing RDoc.
>>>
>>> Why aren't extensions or enhancements to RDoc being made instead?
>> YARD has fairly significant architectural differences that don't lend well to simply writing extensions. YARD is actually a superset of RDoc, and not the other way around, so a merge of functionality wouldn't really work. For instance, YARD is not only a "parse and generate" tool. It is also often used as a 2 phase: "parse and store", "generate from stored data" tool (as exemplified by the 'yard server' tool).
> Sounds like ri -f html.  ri uses RDoc::RI::Store to load data from a stored documentation tree.

Useful. It would be much better if the gem server leveraged this instead 
of forcing the static documentation to be generated on a gem install 
automatically. That is a painfully slow process. YARD only does a 
parse-thru on install (unless you tell it to generate static docs), and 
then dynamically generates the HTML when using yard server --gems. This 
shaves minutes off of some larger gem installs (like Rails), and is a 
much better alternative than adding --no-rdoc to your (which a lot of 
people are doing AFAIK). It also saves plenty of disk space, since few 
users actually access the static gem docs, and those that do can 
generate them on demand with `gem doc` anyway. BTW the YARD server 
actually can do the parsing dynamically too if it wasn't previously 
done, so you don't even need to do any parsing on install, which means 
even *less* time is spent installing. We still do the parse-run for our 
RI implementation though, because there's no way around pre-parsing for 
that.

>> RDoc does not have this phase, so much of the functionality YARD has could not be implemented easily.
> Loading an RDoc::RI::Store and running it back through an HTML generator could be implemented very easily.  The HTML generator may need to be adapted to handle pre-parsed comments which would involve adding two lines.

I think this would be a great move for the reasons given above.

>> YARD's parsing architecture also allows much more leeway to customizing the parsing phase than RDoc's limited markup preprocessing APIs. And yes, these APIs are used in at least a few plugins I know of.
>>
> I built a proof-of-concept parser for Rakefiles:
>
> https://github.com/rdoc/rdoc-rake

Seeing yours, I built a small proof of concept Rakefile parser in YARD 
this afternoon to exemplify the API differences: 
http://gist.github.com/759428

It integrates into the existing template using the same method you are 
using (namespaces as Module, tasks as Method) and also lists 
dependencies of tasks as metadata tags. I fleshed out a more complete 
version that performs better customization to the template and lists the 
Rake tasks in the index page along with the readme files and objects: 
https://github.com/lsegal/yard-rake -- I just might introduce this into 
a future release if it gets a little more work. :-)

>> - Are there any ways to hook into the information generated by directives *after* they've been declared? For instance, can you check for the existence of a specific directive inside of a custom Generator? Again, this kind of functionality is used extremely often in YARD, and is extremely important to outputting documentation for arbitrary @tag-style metadata.
> There is no restriction.  If a directive is unhandled it's stored in the code object's metadata hash.
>

That's good to know, and certainly useful.

>> However, would RDoc be generating documentation for the C API?
> It wouldn't be much work to add, perhaps a week to fully polish.  My boss says I can work on this in place of company business, so I'll give it a shot.

Great. If RDoc was generating the C API and handling the @tags, that 
would help move things along.

- Loren