From: Eric Hodel <drbrain@...7.net>
Date: 2010-04-20T15:57:48+09:00
Subject: Re: Documenting Rakefile using rdoc

On Apr 19, 2010, at 11:58, Jean-Julien Fleck wrote:

> Hello Eric,
> 
>> If it could come in handy why isn't it documented with a desc?
> 
> Because my boss does not wish to :o)

You should tell him what I said :)

>> Hiding documentation behind a separate tool (rdoc-rake) that nobody knows about (just released yesterday) and mostly sucks (honestly, I only released it because you had an interest) is hostile to your users.
> 
> What I would like to give to my (3) coworkers is a Rakefile (designed
> to handle book's compilation in LaTeX and ensure all the data needed
> to make the books have been gathered and up to date) and an online
> documentation (using your tool for which I'm very grateful). They
> would not have to compile the doc themselves. And the Rakefile has to
> be concise with the tasks descriptions because the very last person to
> use it (my boss) should be able to spot the right task to compile all
> the books at once in the right format (even if the editing process the
> intermediate tasks are very useful for us).

Couldn't you make the default task do that so all he has to do is type "rake"?

> I've documented all the tasks in the comments but opening the Rakefile
> to read them is quite tedious and not really productive enough.
> Knowing rdoc, I was just surprised nothing of the kind existed with
> Rakefiles, hence my questions.
> 
> Could you tell me where I should look in order to modify a bit
> rdoc-rake to make it do what I want ?

Right now rdoc-rake ignores comments, so you'd want to uncomment:

http://github.com/drbrain/rdoc-rake/blob/master/lib/rdoc/parser/rake.rb#L257-258

and use that to add an extra block to gather up the TkCOMMENT nodes (you'll have to glue them together yourself).

When you hit a non-comment node set the block to @desc.  You can use RDoc::Text#normalize_comment to clean up the comment for you.

Of course, there are tests to help move you along:

http://github.com/drbrain/rdoc-rake/blob/master/test/test_rdoc_parser_rake.rb

I'd tell you to look at RDoc::Parser::Ruby to figure out how to gather up a comment, but it's really huge and ugly in there.  (I think that code is in #parse_statements though.)