# Rdoc - ignores Rakefile & Rspecs

**URL:** <https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374>\
**Category:** Ruby\
**Created:** [March 28, 2007, 8:37am UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374 "2007-03-28T08:37:04Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 28, 2007, 8:37am UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/1 "2007-03-28T08:37:04Z")

</div>

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 F.

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 29, 2007, 1:22am UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/2 "2007-03-29T01:22:50Z")

</div>

On Mar 27, 2007, at 23:37, Larry F. 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.

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 29, 2007, 9:01pm UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/3 "2007-03-29T21:01:17Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 29, 2007, 1:35pm UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/4 "2007-03-29T13:35:24Z")

</div>

Eric H. wrote:

> On Mar 27, 2007, at 23:37, Larry F. 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 T. 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-talk/130465](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](http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/211297)

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 29, 2007, 10:54pm UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/5 "2007-03-29T22:54:04Z")

</div>

On Fri, Mar 30, 2007 at 04:44:42AM +0900, Suraj K. wrote:

> 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.

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 29, 2007, 9:44pm UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/6 "2007-03-29T21:44:40Z")

</div>

Brian C. 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.

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 30, 2007, 2:36am UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/7 "2007-03-30T02:36:24Z")

</div>

Brian C. wrote:

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

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 30, 2007, 2:38am UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/8 "2007-03-30T02:38:50Z")

</div>

Eric H. 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.

---

<div class="post-metadata">

**Author:** ![lfast](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/l/ee59a6/32.png) [@lfast](https://www.ruby-forum.com/u/lfast)\
**Post date:** [March 30, 2007, 1:20am UTC](https://www.ruby-forum.com/t/rdoc-ignores-rakefile-rspecs/90374/9 "2007-03-30T01:20:29Z")

</div>

On Mar 29, 2007, at 04:35, Suraj K. wrote:

> most central to the Ruby experience? Why can’t this be this fixed  
> instead? Although it was written by Dave T. 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.)