Using comments as rake task descriptions

Over lunch at Scotland on Rails, Jim, Chad, and I got talking about the way you use desc to document tasks in rake.

desc "Remove intermediate files and other work products"
task :cleanup do
  ...
end

This has always been an interesting feature of rake—the idea that you have a kind of temporal coupling between one method call and the next. It works well, but somehow it's always struck me as a little obtrusive.

So, during the afternoon, I hacked up a quick change to rake that looks for a single-line comment on the line prior to all task, file, etc directives, and uses that as the task description. With this version of rake,  you can write

# Remove intermediate files and other work products
task :cleanup do
  ...
end

The comment becomes the description of the task, because it occurs before the task directive with no intervening blank line. desc still works, and if both desc and a comment are present, the desc takes priority. It's purely a matter of taste, but I personally find the comment form more natural.

You can get this patched version from http://github.com/pragdavespc/rake/tree/master. I've passed the patch on to Jim, so if you like the idea, let him know and maybe he'll roll it into the next rake release.

Comments

[Martijn Lafeber]

Looks way better. This should definitely be in the next release.

[lasso]

I think something like

task :cleanup, "Remove intermediate files and other work products" do
# Do stuff
end

looks more natural. After all, the description is a property of the task.

[Sam Aaron]

My problems is that, although it's a pretty neat trick, using comments doesn't really fix the temporal coupling issue you described - it just hides it a little bit more with further magic.

I would much prefer something like lasso's approach where you tightly couple the description in the task method, you could easily add it as an option to the opts hash:

task :cleanup, :desc => "Remove intermediate files and other work products" do
#Do stuff
end

On a side note, this is actually one of the things I really like about the language Ioke: each method has an optional documentation cell. It's perfect for things like this :-)

[Daniel Sandbecker]

I think the example shows the most important benefit - with syntax highlighting the description is much more visible when the description is not just another string.

[Patrick]

This change requires reading the file for every undocumented task. For a complex task tree this would be a huge performance killer. I don't care for it myself.
Also, people understand what comments are, and that they're not interpreted or compiled in anyway. To have them injected indirectly into the closest task? No thanks.

[Jake]

-1

IMO, comments should stay comments. Such a feature would definitely not adhere to the principle of least surprise...

[Phil]

Ah, stealing features from Lisp... a time-honored tradition. Does this use the AST or just hand-parsing from caller?

[Derek Perrault]

I definitely agree with Iasso, Sam Aaron, and Jake. I'd rather be able to set the description as a property of the task.

[Daniel Lucraft]

This is nice except in situations where you are dynamically generating tasks and therefore need to dynamically generate description strings. For that desc is necessary.

[ara.t.howard]

i think all the approaches are fairly fugly, including the current rake behaviour. it'd be a super small backward compatible change to simply support

task "this is the description", :name => "taskname", ...

with about 2 lines of argument parsing. probably supporting

task "this is the description", "taskname"

would be good too. i see no advantage whatsoever for separating the annotation from call to task.