Assume the following tasks were written for Rake 0.8.x.
# This comment describes a non-toplevel-task.
task :complex_task do
# ...
end
# For internal use only -- washes laundry, takes out trash, other
# crap.
task :house do
# ...
end
#
# I prefer this comment style.
#
task :style do
# ...
end
#### output of rake --tasks:
rake complex_task # This comment describes a non-toplevel-task.
rake house # crap.
Fortunately my own commenting style avoids this problem. Others will
likely encounter some annoyance (small or possibly great).
One could make the comment-grabber smarter, but the question is: How
should a programmer document a top-level task? There is already an API
method for doing so: desc. The new comment-to-desc feature does not
solve an actual problem or deficiency.
There could hundreds of these new magic-comment 'desc's cropping up,
making the --tasks output useless. Even one newly-public comment could
be an issue (think of a programmer making a veiled complaint about a
co-worker). A programmer may have good reason to use '#' instead of
'desc'. Why should a new version of Rake suddenly dismiss that reason?
Surely there is someone out there who wrote
(0...1000).each do |i|
# blah blah ...
task "blah#{i}" do
# ...
end
end
#### rake --tasks output:
rake blah0 # blah blah ...
rake blah1 # blah blah ...
rake blah10 # blah blah ...
rake blah100 # blah blah ...
rake blah101 # blah blah ...
rake blah102 # blah blah ...
rake blah103 # blah blah ...
rake blah104 # blah blah ...
rake blah105 # blah blah ...
rake blah106 # blah blah ...
rake blah107 # blah blah ...
rake blah108 # blah blah ...
rake blah109 # blah blah ...
rake blah11 # blah blah ...
rake blah110 # blah blah ...
rake blah111 # blah blah ...
rake blah112 # blah blah ...
...
In exchange for annoying that programmer, what do we get in return?
Usually compatibility is purposefully broken in order to fix a flaw.
What is the flaw in 'desc'? Why is '#' better than 'desc'?
The worst-case scenario is an auto-generated web page of the --tasks
output. With the new Rake, a password in the comments gets exposed.
Previously '#' meant internal documentation for a non-top-level task.
Now it means public documentation for a top-level task, an effective
alias of 'desc'. For internal docs, leave a space between the comment
and the task definition. That is natural for me, but requiring all
programmers to do that in all Rakefiles seems rather unnatural.
_______________________________________________
Rake-devel mailing list
[email protected]
http://rubyforge.org/mailman/listinfo/rake-devel
