From: Eric Hodel <drbrain@...7.net>
Date: 2008-03-30T11:53:52+09:00
Subject: Re: Improvements to RDoc (ideas for GSoC)

On Mar 29, 2008, at 14:20 PM, Rodrigo Almeida wrote:
> I'm a brazilian student wishing to participate in Google Summer of
> Code this year, and work on something related to RDoc. Before I finish
> my proposal, I'd like some community feedback on the ideas below

Hi, I'm the current maintainer of RDoc.

I have made some refactorings and minor improvements to RDoc for Ruby  
1.9.  If you decide to continue with this project, please make your  
changes against 1.9 so they will be easy for me to merge in.

(The RDoc that ships with 1.8 is RDoc 1.0.1, the RDoc that ships with  
1.9 I have changed to RDoc will be RDoc 2.)

> First of all, I think documentation of any Ruby library can be split
> in two different sections: Reference, which is documenting every class
> and method on the library, in a way that's easy for one to access
> information on a specific feature, and a more general documentation,
> which is not bounded to any Ruby code directly. This part of
> documentation would include an overview of the library, tutorials and
> stuff like that. More "common" libs, like a String library, probably
> don't really need the second part, but as I was designing a ACL plugin
> for a Rails project I'm participating, I found that having a separate
> section of the documentation for explaining how ACL works, system
> concepts and some additional tutorials would be a nice add. RDoc sort
> of currently supports through files without extension like README or
> CHANGELOG, but that makes this documentation accessible only though
> the Files menu.

In the past I've used the appropriate class for the location of  
overview/tutorial/how-to documentation, but I agree it is not optimal.

> This leads to another important aspect. I think that RDoc shouldn't
> include that Files menu

I don't like the Files list either, I don't find it helpful for  
navigating the documentation.

> it should be structured more like a Table of
> Contents. So, for me, the best layout would be having a left
> navigation menu, and my ACL plugin documentation menu could look
> something like that:
>
>> Introduction
>> System Concepts
>> What is an ACL?
>> Privileges
>> Selectors
>> Tutorials
>> ...
>> Reference
>> [Object Browser-like structure]
>
> This kind of layout is already implemented by Noobkit. See:
> http://www.noobkit.com/show/ruby/ruby.html
>
> My idea is not to force every RDoc generated to look like above, but
> improve current RDoc system so that the layout above can be achieved
> by simply using a special template. Currently, RDoc templates are Ruby
> Modules which define a lot of string constants, containing
> placeholders, which results in template construction and readability
> being far from ideal. The already suggested idea of changing RDoc to
> use ERb templates would be really appropriate here, we could really
> use some inspiration from rails and use partials to render the
> different elements in the page, and have a main template file that
> puts everything together.

RDoc 2 has an ERb-based template system that makes it easy to convert  
RDoc 1.x templates.

I think it would be OK to switch to a completely different ERb-based  
template system.  (For example, there is a ruby object -> Hash/Array/ 
Hash conversion that happens to support the old template system, but  
it is not necessary for ERb.  Removing this conversion would make it  
easier to make more-flexible templates.)

> For implementing code-unrelated documentation, one idea would be to
> define a default folder (let's say, /add_doc), which, if present on
> the source code root folder, would be parsed by RDoc and added to the
> documentation table of contents. Each file inside this dir should call
> a title directive on its first line, to define that page's title. So,
> the TOC above could be generated by the following file structure:
>
> /add_doc/intro.rdoc
> /add_doc/concepts.rdoc
> /add_doc/concepts/acl.rdoc
> /add_doc/concepts/privileges.rdoc
> (...)

Or, maybe simply an rdoc/ directory, since the rdoc command-line tool  
generates documentation into doc/ by default.

> Currently RDoc already can be extended to add support for other forms
> of markup (see doc for RDoc::Page), but this could be improved, as to
> accept additional markup tags and modifiers in an easy way. Let's say
> I used to work with java and wanted to comment a method like in the
> example below.
>
> # Method description here
> #
> # ::params::
> #       url: an absolute URL giving the base location of the image
> #       name: the location of the image, relative to the url argument
> # ::return::
> #       the image at specified URL
> # ::see::
> #       Image
> #
> def load_image(url, name) #:takes: String, String; #:returns: Image
>
> It should be viable for someone to come up with an RDoc extension that
> can generate the JavaDoc-like output from the comments above without
> excessive digging into RDoc's source.
>
> Those are my preliminary ideas, any feedback on those would be really
> appreciated.

I am not sure how easy it is to add additional directives (on the def  
line) to RDoc, I haven't looked.  Adding additional markup inside a  
comment is much easier and (I think) could be achieved with a mixin  
module.

However, I agree with Dave here.  I find documentation easier to write  
if it reads like a sentence.  This is an example of some documentation  
I wrote:

class Gem::Requirement

   ##
   # Constructs a Requirement from +requirements+ which can be a  
String, a
   # Gem::Version, or an Array of those.  See parse for details on the
   # formatting of requirement strings.

   def initialize(requirements)
   end

(RDoc will automatically link "parse" to the parse method's  
documentation.  I only bothered to mark up "requirements" to draw the  
eye.)