RDOC Question -- including parent class accessors, and linking other classes

[John Wilger]

Hello,

I apologize for the cross-post, but I was advised that this list is a
lot more active than the ruby-doc list and I might get an answer
faster by posting my question here. Please see below:

Hello,

I have acouple of quick questions regarding RDOC, but I can't seem to
find the information anywhere in the RDOC documentation (or even with
a Google search).

Lets say I have a parent class like:

class ParentClass
attr_reader arent_reader
end

And I have a child class like:

class ChildClass
attr_reader :child_reader
end

What would I have to do to have both "ChildClass#child_reader" _and_
"ChildClass#parent_reader" documented in the RDOC class file for
ChildClass? Currently, I only see "ChildClass#child_reader" in the
docs for ChildClass, and you have to view the parent class to see the
documentation for "ParentClass#parent_reader".

Also, my generated RDOC documentation does not seem to automatically
be creating links out of class names in the documentation. I am
developing an application with Rails, and I have some code placed in
the 'lib' subdirectory. In some of the documentation comments, I refer
to the name of a model class which is stored in the 'app/models'
subdirectory. However, the HTML documentation does not create a link
from the class in 'lib' to the model class when I run rdoc from the
command line above both directories. Any thoughts?

--
Regards,
John Wilger

-----------
Alice came to a fork in the road. "Which road do I take?" she asked.
"Where do you want to go?" responded the Cheshire cat.
"I don't know," Alice answered.
"Then," said the cat, "it doesn't matter."
- Lewis Carrol, Alice in Wonderland

 

[Dave Thomas]

RDoc doesn't currently let you do this: the problem really is knowing
where to stop--do you document all of the parent's methods, and its
parent's methods, and so on.

I'm open to ideas here.

Could you email me a minimal set of source files that exhibit the
problem?

Cheers

Dave

 

[John Wilger]

My reply didn't go to the list due to the attachment I was sending to
Dave, so here it is.

Dave,

I doubt the list allows attachments, so I put your address in the 'to'
field as well so you can get the sample code.



How about including a tag like "#:document_inherited:"? This would
include the inherited methods/accessors of the immediate parent only
in the current class. However, if the immediate parent also specified
the "#:document_inherited:" tag, then the child class would document
it's grand-parent's methods/accessors as well (unless they were
overriden down the chain), and so on, and so forth on up the line.


I think I figured out what is causing the problem. The class inside
the 'lib' directory is defined within a module, but the class inside
'app/models' is not. Apparently RDOC will only create the link to
other classes within its namespace if you don't specify the namespace
explicitly. So what would the explicit namespace be for a class that
isn't inside a module?

I've attached a paired down sample for you to look at.

--
Regards,
John Wilger

-----------
Alice came to a fork in the road. "Which road do I take?" she asked.
"Where do you want to go?" responded the Cheshire cat.
"I don't know," Alice answered.
"Then," said the cat, "it doesn't matter."
- Lewis Carrol, Alice in Wonderland

 

[Dave Thomas]

I think I figured out what is causing the problem. The class inside
the 'lib' directory is defined within a module, but the class inside
'app/models' is not. Apparently RDOC will only create the link to
other classes within its namespace if you don't specify the namespace
explicitly. So what would the explicit namespace be for a class that
isn't inside a module?

Strangely, the stuff you sent me worked here (at least the link to the
Project class worked from the ProjectStatus class). Are you running the
latest RDoc?


Cheers

Dave