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.
-
Are there any other potential problems with using this approach?
-
Is there a better way to do it?
Stephan D. wrote:
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.
–
James B.
“I often work by avoidance.”
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: