[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

rdoc and virtual attributes

Stephan Dale

7/29/2007 5:57:00 PM

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?
--
Posted via http://www.ruby-....
2 Answers

James Britt

7/29/2007 6:33:00 PM

0

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

Stephan Dale

7/31/2007 11:54:00 AM

0

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:
--
Posted via http://www.ruby-....