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.
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.
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.
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
and http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/211297
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.
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.
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.
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.
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.)
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.
Sponsor our Newsletter | Privacy Policy | Terms of Service | Remote Ruby Jobs