[RDOC] Documenting accessor methods as methods

[Gavin Sinclair]

That's where we differ, and why RDoc distinguishes between attr and
regular method definitions. It isn't just a macro facility: it's an
expression of intent.

I agree with this; I like (on balance) seeing attributes documented
separately; and I would like to see an :attr: directive introduced.

But there's one problem as I see it at the moment: attributes don't
appear in the method pane. This sometimes incurs difficulties: try to
find a method (you don't know what class) in a large body of
documentation, only to discover it's an attribute.

Gavin

 

[Dave Thomas]

But there's one problem as I see it at the moment: attributes don't
appear in the method pane. This sometimes incurs difficulties: try to
find a method (you don't know what class) in a large body of
documentation, only to discover it's an attribute.

Do you mean the list at the top? That's a good point. I could probably
work them in there. Should they be intermingled, or listed separately?

Cheers

Dave

 

[Jim Weirich]

Dave Thomas said:

Do you mean the list at the top? That's a good point. I could probably
work them in there. Should they be intermingled, or listed separately?

Intermingled ... on the theory that if you are looking up a method in the
list, you would like to check one place rather than many.

 

[Michael Neumann]

Dave Thomas said:

Intermingled ... on the theory that if you are looking up a method in the
list, you would like to check one place rather than many.

Hm, and how about methods inherited from a superclass? Shouldn't they be
shown there either? Or at least in a section called "methods inherited
by superclass".

Regards,

Michael

 

[Dave Thomas]

Hm, and how about methods inherited from a superclass? Shouldn't they
be
shown there either? Or at least in a section called "methods inherited
by superclass".

All the way up to Object?


Cheers

Dave

 

[Gavin Kistner]

Hm, and how about methods inherited from a superclass? Shouldn't they
be
shown there either? Or at least in a section called "methods inherited
by superclass".

I think so. This is my biggest complaint with almost all documentation
of OOP hierarchies, and what drove me to write
http://phrogz.net/ObjJob/ for documenting hierarchies myself. I
personally like them intermingled with a sprig of 'DHTML' to show/hide
inherited ones.

(For example, see the DOM 2 MouseEvent interface:
http://phrogz.net/ObjJob/object.asp?id=222
and note the inherited properties/methods, also showing from where they
are inherited, and the ability to toggle the checkbox to hide/show the
inherited ones.

 

[Michael Neumann]

All the way up to Object?

No, you're right, that's a bad idea.

But would be nice, if method names in the documentation would be
detected for superclasses. Example:

class A
def a; end
end

class B < A

# Calls method a <-----
def b
end

end

So that "a" would be a pointer to A#a.

But I can live very good with writing explicitly A#a.

Regards,

Michael

 

[Gavin Sinclair]

Dave Thomas said:

Intermingled ... on the theory that if you are looking up a method in the
list, you would like to check one place rather than many.

Yes. Just to be precise, I was referring to the method _frame_ (I
wrote "pane").

One day I imagine there'll be a webapp for searching bodies of RDoc
information

Gavin

 

[Jim Weirich]

Dave Thomas said:

All the way up to Object?

Eiffel documentation systems typically gave the users a choice: they could
view methods only immediately defined in the class, or with a click of a
button, they could have a flattened view of the method list. The flat
view was great for clients of a class that don't particularly care where
it lies in the class tree, they just want to know what methods can be
called on the object.

However, I think the flat view didn't include methods at the Object level
(I'd have to check to make certain).

This works best as interactive program. Statically generating the HTML
for both views may be overkill. Hmmm ... perhaps something like the
inline source hack ... a show/hide button could enable disable the
ancestor methods.

Just an idea.