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?
on 2007-07-29 21:57
on 2007-07-29 22:34
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." - Brian Eno
on 2007-07-31 15:54
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: