Asp Forum - Rdoc - ignores Rakefile & Rspecs

Larry Fast

3/28/2007 6:37:00 AM

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

--
Posted via http://www.ruby-....

8 Answers

Eric Hodel

3/28/2007 11:22:00 PM

On Mar 27, 2007, at 23:37, Larry Fast wrote:

> 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

3/29/2007 11:35:00 AM

Eric Hodel wrote:
> On Mar 27, 2007, at 23:37, Larry Fast wrote:
>
>> 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.
>
> 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
ruby

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

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

--
Posted via http://www.ruby-....

Brian Candler

3/29/2007 7:00:00 PM

On Thu, Mar 29, 2007 at 08:35:25PM +0900, Suraj Kurapati wrote:
> 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
> ruby

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

3/29/2007 7:45:00 PM

Brian Candler wrote:
> 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.

--
Posted via http://www.ruby-....

Brian Candler

3/29/2007 8:53:00 PM

On Fri, Mar 30, 2007 at 04:44:42AM +0900, Suraj Kurapati wrote:
> Brian Candler wrote:
> > 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

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

3/29/2007 11:20:00 PM

On Mar 29, 2007, at 04:35, Suraj Kurapati wrote:
> Eric Hodel wrote:
>> On Mar 27, 2007, at 23:37, Larry Fast wrote:
>>> 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.
>>
>> 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

3/30/2007 12:36:00 AM

Brian Candler wrote:
> On Fri, Mar 30, 2007 at 04:44:42AM +0900, Suraj Kurapati wrote:
>> 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.

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.

--
Posted via http://www.ruby-....

Suraj Kurapati

3/30/2007 12:39:00 AM

Eric Hodel wrote:
> 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.

--
Posted via http://www.ruby-....

comp.lang.ruby

Rdoc - ignores Rakefile & Rspecs

Larry Fast

Eric Hodel

Suraj Kurapati

Brian Candler

Suraj Kurapati

Brian Candler

Eric Hodel

Suraj Kurapati

Suraj Kurapati

x Login to ForumsZone