Problem with RDoc

[Chris Gehlker]

I have discovered an issue with RDoc that may or may not be old news,

Say I have a folder with a file named my_class.rb and a subfolder
named my_class. Within the my_class folder are two files named a.rb
and b.rb. a.rb contains:

class My_Class
def methA
...
end

def methB
...
end
end

while b.rb contains:

class My_Class
def methC
...
end

def methD
...
end
end

my_class.rb contains:

require 'my_class/a.rb
# there is no mention of b.rb here

RDoc will still document My_Class as having the methods in file b.rb

I don't know if this issue has been raised before and if it is worth
the trouble to address.

---
Neither a man nor a crowd nor a nation can be trusted to act humanely
or to think sanely under the influence of a great fear.

-Bertrand Russell, philosopher, mathematician, author, Nobel laureate
(1872-1970)

 

[Dave Thomas]

my_class.rb contains:

require 'my_class/a.rb
# there is no mention of b.rb here

RDoc will still document My_Class as having the methods in file b.rb

RDoc documents the files you give it--it doesn't execute the code to
find out what files you use. You have two files, each of which adds
methods to My_Class, so it documents both sets of definitions.

Regards


Dave Thomas

 

[Chris Gehlker]

RDoc documents the files you give it--it doesn't execute the code
to find out what files you use. You have two files, each of which
adds methods to My_Class, so it documents both sets of definitions.

Exactly.

I think one could make a good argument that this is the *right*
behavior. It can be a bit surprising though, given the practice of
some Ruby developers of distributing files that are 'in progress'
along with the files are actually required in their projects.
Sometimes these 'in progress' files actually contain more extensive
RDoc documentation than the files that are actually required into the
main class.

 

[Dave Thomas]

Exactly.

I think one could make a good argument that this is the *right*
behavior. It can be a bit surprising though, given the practice of
some Ruby developers of distributing files that are 'in progress'
along with the files are actually required in their projects.
Sometimes these 'in progress' files actually contain more extensive
RDoc documentation than the files that are actually required into
the main class.

You can use --exclude to ignore those files that are in development.


Dave

 

[Chris Gehlker]

You can use --exclude to ignore those files that are in development.

Great suggestion. I don't know how i missed that.