[Rake-devel] Rake DSL Commands are no long in top level

Alex Chaffee alexch at gmail.com
Fri Jun 5 12:14:59 EDT 2009

> Anyhow, this is going beyond the main topic here, test the branch and
> send the comments with real life usage.

My concern with this has nothing to do with performance. I think it's
a bad idea to twist  the definition of the Ruby language (and
programming languages in general), which says that comments are to be
seen by people who use the *code*, and not by those who use the

Rdoc is arguably an excusable exception here because the audience for
its output is also people who are using the code, not running the
program. But I'm responding to Dave's mention of rdoc comments -- I'm
not suggesting an rdoc rewrite, but I see that as a slippery slope,
not a useful precedent...

On Fri, Jun 5, 2009 at 12:37 AM, Alex Chaffee<alexch at gmail.com> wrote:
> Yeah, I agree: rdoc is also astonishing. Why isn't it
> rdoc """
> This method is awesome.
> """
> def awesome
>  11
> end
> ?

On Thu, Jun 4, 2009 at 8:54 PM, Luis Lavena<luislavena at gmail.com> wrote:
> Maybe because that's not the Ruby syntax for comments?

I think you're missing my point. Code comments have many uses, but
rdoc (and rake if this patch stays in) has changed their semantics in
a destructive way. If I want to put a comment in the code that's
intended to describe the method to other coders -- say, "oy, this
method needs to be optimized" -- then I can't put it right above the
method, because then it will appear in the public API documentation.
(I wonder how many rdoc pages in the world have inadvertently exposed
"todo" comments?)

Alex Chaffee - alex at stinky.com - http://alexch.github.com
Stalk me: http://friendfeed.com/alexch | http://twitter.com/alexch |

More information about the Rake-devel mailing list