rdoc and virtual attributes

[Stephan Dale]

I've been trying to get rdoc to document virtual attributes as though
they weren't virtual. The solution seems to be to use an attr_reader /
attr_writer as an anchor for the documentation with the :nodoc: modifier
on the getter / setter methods, like so:

class ClassName

# Documentation for virtual_var.
attr_writer :virtual_var

def virtual_var # :nodoc:
# "get" virtual_var
end

def virtual_var=(whatever) # :nodoc:
# "set" virtual_var
end

end

Doing this results in rdoc documenting the virtual attribute alongside
the normal attributes and not documentating the virtual attribute getter
/ setter methods. So, to the reader, the fact that the attribute is
virtual is completely hidden.

The main problem with this approach seems to be that it places a greater
responsibility on the programmer to ensure that there is no mismatch
between what a ClassName instance reports its variable to be and what
the getter method says it is.

1. Are there any other potential problems with using this approach?

2. Is there a better way to do it?

 

[James Britt]

The main problem with this approach seems to be that it places a greater
responsibility on the programmer to ensure that there is no mismatch
between what a ClassName instance reports its variable to be and what
the getter method says it is.

Why is that a problem? The public interface should not be coupled to
the implementation, nor expose implementation details.

Knowing that an object responds to foo= should not mean I can count on
the object having an instance variable named @foo.

 

[Stephan Dale]

I'm just worried that by using the attr_ methods where you'd not
normally do so, simply for documentaion purposes, increases the risk
that you forget their programmatic effects.

e.g. I've defined a virtual attribute called foo and I've used
attr_writer to document it as a normal attribute. Problem is that I've
forgotten to override the setter. By inspection we can see that the use
of foo= sets @foo, but foo doesn't get @foo, hence showing that foo is a
virtual attribute and exposing some of the underlying implementation.

class Bar

# foo isn't a virtual attribute, honest!
attr_writer :foo

# oh yes it is.
def foo # :nodoc:
@foo+1
end

end

irb(main):011:0> b = Bar.new
=> #<Bar:0xb78fd04c>
irb(main):012:0> b.foo = 1
=> 1
irb(main):013:0> b
=> #<Bar:0xb78fd04c @foo=1>
irb(main):014:0> b.foo
=> 2

I was hoping that there was a way of flagging a method as representing a
virtual attribute rather than having to rely on the attr_ methods.

e.g. def foo # :virtual: