Re: [PATCH] rdoc capture output (help message)

On Sep 29, 2006, at 5:52 AM, greg weber wrote:

> It looks like you could seperate this out into a rake task, but  
> then you would have a hard-coded dependency between your program  
> and the rake task.

If a dependency already exists between the rdoc command and your  
program then writing it down only makes it easier to maintain.

> Now every script that I have will require a rake task to generate  
> documentation instead of just running rdoc.

Most of my projects include a Rakefile.  Most everybody's projects  
I've seen include some kind of script to perform installation.  Since  
rake tasks and make rules can be abstracted and reused, I don't see  
how this is more onerous than remembering a complicated rdoc option  
you use only once in a while.

You're also end up typing less.  "rake rdoc" instead of "rdoc -C blah  
blah blah".

> And if someone else uses and modifies the script and wants to  
> document it they will have to create a rake task.

And how are they supposed to know the correct arguments to -C?

> There are probably lots of things built into Ruby that could be  
> seperated into a rake task, but that would not be very  
> convennient.  Also, I think this is a feature that many beginners  
> that are not already familiar with rake may want to use.

rake and make are standard developer tools.  Their are plenty of  
examples out there that will allow people to write the equivalent of:

   mycommand --help > mycommand.help
   rdoc lib mycommand.help

> I started documenting usage for my scripts using RDoc::Usage- under
> the premise that it followed the motto Don't Repeat Yourself.  Then I
> discovered that when I changed something about my options I was
> maintaing both my options and my RDoc documentation, and I was not
> following DRY.

If you're typing in "rdoc -C blah blah blah" by hand every time you  
make documentation you are repeating yourself.  Put that in a rake  
task or make rule.

> What is the downside to including this?

You haven't shown or described how it behaves with multiple executables.

You haven't shown or described where the generated documentation lives.

But most importantly...

It is not the simplest thing that works.  It is a feature that RDoc  
already handles just fine through both parsing of plain text files  
and the :include: directive.

-- 
Eric Hodel - [e-mail] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com