Rdoc - ignores Rakefile & Rspecs

[Larry Fast]

Is it possible to get Rdoc to generate information about Rakefiles? It
seems that I can't ask it to parse files that don't have an extension.

Is it possible to get Rdoc to generate information about Rspec
specify-cations? It happily reads the files but produces no output since
there are no Classes or Methods.

Thanks,
Larry Fast

 

[Eric Hodel]

Is it possible to get Rdoc to generate information about
Rakefiles? It
seems that I can't ask it to parse files that don't have an extension.

Is it possible to get Rdoc to generate information about Rspec
specify-cations? It happily reads the files but produces no output
since
there are no Classes or Methods.

Nope.

As a workaround, move logic you want documented out of the Rakefile.

 

[Suraj Kurapati]

As a workaround, move logic you want documented out of the Rakefile.

=begin
How long do we have to keep working around flaws in programs that are
most central to the Ruby experience? Why can't this be this fixed
instead? Although it was written by Dave Thomas and friends, rdoc is
not perfect[1]. If this were 1997 instead of 2007, I'd bet this issue
would be fixed almost instantaneously.
=end

It is understandable that rdoc ignores such files when it regresses
directories automatically. That is, when it is run with either (1) no
command-line arguments or (2) command-line arguments which are
directories.

However, I think its file-extension based discrimination is implemented
too strongly. So strongly, in fact, that it frustrates and alienates the
user by counter-intuitively ignoring _explicitly_ specified command-line
arguments.

For example, when I run

rdoc foo_bar

I expect rdoc to parse the foo_bar file *indiscriminately* -- why does
it care what file name I specify? I, the user, a human being no less,
have stated explicitly that I would like it to parse that file... it
should *not* ignore me! :-(


Furthermore, rdoc does not operate on the standard input stream. I live
in *NIX land, so it is reasonable for me to expect that rdoc would
behave like a filter:

cat foo_bar | rdoc

At least, it should accept '-' as an identifier for the standard input
stream:

cat foo_bar | rdoc -

In contrast, observe how newer tools (such as RedCloth) are
indiscriminate to file extensions and play nicely with the standard
input stream:

% echo '*ruby*' | redcloth
<p><strong>ruby</strong></p>

% redcloth foo_bar # it doesn't care about file extension!


[1] http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/130465
and http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/211297

 

[Brian Candler]

Furthermore, rdoc does not operate on the standard input stream. I live
in *NIX land, so it is reasonable for me to expect that rdoc would
behave like a filter:

cat foo_bar | rdoc

I live in *NIX land, and I would *not* expect rdoc to work that way. It has
to collate information from a whole series of different sources to build its
file, class and method indexes - basically it has to read and parse
everything before it can generate output. And it needs to know the names of
each of the source files to build the file index.

rdoc which worked on a single file would not be much like the current rdoc.

I think a summary of the problem is: you want rdoc to process a file as if
it were ruby source, but where it has no extension. Or: rdoc doesn't let you
specify on a file-by-file basis whether it's plain text or ruby source.
Correct?

A simple workaround, I think, is to rename Rakefile to Rakefile.rake
(or make a symlink from Rakefile.rake to Rakefile), and then use
rdoc -E rake=rb

In contrast, observe how newer tools (such as RedCloth) are
indiscriminate to file extensions and play nicely with the standard
input stream:

% echo '*ruby*' | redcloth
<p><strong>ruby</strong></p>

redcloth is a completely different kettle of fish: it's a filter which
converts one blob of text into another blob of text. It's nothing to do with
redcloth being "new" and rdoc being "old".

Brian.

 

[Suraj Kurapati]

I think a summary of the problem is: you want rdoc to process a file as
if it were ruby source, but where it has no extension.

I want rdoc to process a file as if it were ruby source *regardless* of
its file extension when it is explicitly specify as a command-line
argument. For example, this should work:

ln foo.rb foo.exe

rdoc foo.exe # should treat foo.exe as a ruby source file

rdoc put_odd_name_here # should treat as ruby source file

In other words, rdoc should *not* discriminate files (specified as
command-line arguments) based on their (possibly nonexistent) file
extension. Just think of how cat(1) processes files indiscriminately.

As for directories, rdoc's behavior of ignoring non *.rb files whilst
automatically regressing directories is acceptable. Though, it might be
nice to specify a file-path glob that rdoc would process whilst
regressing:

rdoc some_project/lib/ --allow '[Rr]akefile' --allow
'**/*.{rake,ruby}'

Or: rdoc doesn't let you specify on a file-by-file basis whether it's
plain text or ruby source.

I would not like this alternative because would require far too much
typing:

rdoc foo.exe --allow foo.exe bar.exe --allow bar.exe ...

If the basis were more coarse grained (say, by file-path glob) then it
might be more managable:

rdoc foo.exe bar.exe --allow '*.exe' ...

Nevertheless, I highly prefer *no* file-extension based discrimination,
because it is simple and straightforward, over these
special-case-provision alternatives.

 

[Brian Candler]

I want rdoc to process a file as if it were ruby source *regardless* of
its file extension when it is explicitly specify as a command-line
argument.

For example, this should work:

ln foo.rb foo.exe

rdoc foo.exe # should treat foo.exe as a ruby source file

rdoc put_odd_name_here # should treat as ruby source file

But that breaks the very common idiom of:

rdoc doc/README

which clearly is *not* a ruby source file.

Nevertheless, I highly prefer *no* file-extension based discrimination,
because it is simple and straightforward, over these
special-case-provision alternatives.

Whilst breaking the majority of existing users of rdoc. I guess your
solution would require them to rename plain text files to *.txt

Brian.

 

[Eric Hodel]

As a workaround, move logic you want documented out of the Rakefile.

=begin
How long do we have to keep working around flaws in programs that are
most central to the Ruby experience? Why can't this be this fixed
instead? Although it was written by Dave Thomas and friends, rdoc is
not perfect[1]. If this were 1997 instead of 2007, I'd bet this issue
would be fixed almost instantaneously.
=end

[... more feature requests/bug reports reported in the wrong
place ...]

Have you submitted a patch to the RDoc tracker? With tests? I just
looked, and didn't see one that seemed to match. Apologies if I
missed it.

If I haven't missed it, quit complaining and start patching.

Ruby and RDoc are open source, which means *YOU* are equally
responsible for making RDoc awesome as anybody else. Open source
does not mean you have the right or even expectation of the author or
maintainer doing anything for you, especially when you offer
complaints instead of patches.

(Alternately, you can bribe me into fixing anything I'm the
maintainer of, otherwise I'll fix it as I see fit.)

 

[Suraj Kurapati]

But that breaks the very common idiom of:

rdoc doc/README

which clearly is *not* a ruby source file.

Ah, good point. I did not consider this case.

Whilst breaking the majority of existing users of rdoc. I guess your
solution would require them to rename plain text files to *.txt

You're correct. I withdraw my proposition, in this light.

Thanks for your explanation.

 

[Suraj Kurapati]

Have you submitted a patch to the RDoc tracker? With tests? I just
looked, and didn't see one that seemed to match. Apologies if I
missed it.

If I haven't missed it, quit complaining and start patching.

I apologize for my rudeness. You are correct.

I'll submit a patch for RDoc.usage(__FILE__) soon.