Forum: Ruby rdoc and virtual attributes

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
1924957eee03ddf35a65a3e8337f7f20?d=identicon&s=25 Stephan Dale (stephan)
on 2007-07-29 19:57
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?
Ff9e18f0699bf079f1fc91c8d4506438?d=identicon&s=25 James Britt (Guest)
on 2007-07-29 20:34
(Received via mailing list)
Stephan Dale 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 Britt

"I often work by avoidance."
- Brian Eno
1924957eee03ddf35a65a3e8337f7f20?d=identicon&s=25 Stephan Dale (stephan)
on 2007-07-31 13: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:
This topic is locked and can not be replied to.