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


 

Forums >

comp.lang.ruby

[RDOC] Documenting accessor methods as methods

James Britt

11/6/2004 11:23:00 PM

I sometimes use the method definition shorthand 'attr_reader',
'attr_writer', and the like to create accessor methods without having to
type out the long form.

rdoc documents these methods as 'attributes'; I'd rather the methods be
documented as methods. Is there a way to tell rdoc to include them
along with the other methods?

I know that I can get this result if I manually write out the long form
of these methods, but I'd really rather not have to do that.


Thanks,


James
28 Answers

Gavin Kistner

11/7/2004 12:35:00 AM

0

On Nov 6, 2004, at 4:23 PM, James Britt wrote:
> I sometimes use the method definition shorthand 'attr_reader',
> 'attr_writer', and the like to create accessor methods without having
> to type out the long form.
>
> rdoc documents these methods as 'attributes'; I'd rather the methods
> be documented as methods. Is there a way to tell rdoc to include them
> along with the other methods?
>
> I know that I can get this result if I manually write out the long
> form of these methods, but I'd really rather not have to do that.

And vice-versa...I frequently do something like:

# The foo attribute
attr_accessor :foo
def foo=(n) #:nodoc:
#...special setter code necessary
end

Specifically so that RDoc will document 'foo' as a RW attribute. The
downside of the above is that ruby complains about the redefinition of
#foo= if warnings are enabled.

What I'm saying is that I'd like a way to tell RDoc to document a
certain method as an attribute.

Dave Thomas

11/7/2004 3:37:00 AM

0


On Nov 6, 2004, at 18:35, Gavin Kistner wrote:

> And vice-versa...I frequently do something like:
>
> # The foo attribute
> attr_accessor :foo
> def foo=(n) #:nodoc:
> #...special setter code necessary
> end
>
> Specifically so that RDoc will document 'foo' as a RW attribute. The
> downside of the above is that ruby complains about the redefinition of
> #foo= if warnings are enabled.
>
> What I'm saying is that I'd like a way to tell RDoc to document a
> certain method as an attribute.

try

rdoc --accessor foo ...

Cheers

Dave

Paul van Tilburg

11/7/2004 9:16:00 AM

0

On Sun, Nov 07, 2004 at 12:36:40PM +0900, Dave Thomas wrote:
> On Nov 6, 2004, at 18:35, Gavin Kistner wrote:
>
> >And vice-versa...I frequently do something like:
> >
> > # The foo attribute
> > attr_accessor :foo
> > def foo=(n) #:nodoc:
> > #...special setter code necessary
> > end

Maybe something like:
def foo=(n) # :attrib:
is better?

> >Specifically so that RDoc will document 'foo' as a RW attribute. The
> >downside of the above is that ruby complains about the redefinition of
> >#foo= if warnings are enabled.
> >
> >What I'm saying is that I'd like a way to tell RDoc to document a
> >certain method as an attribute.
>
> try
>
> rdoc --accessor foo ...

Thanks, that works. However, I use a script to generate documentation on
svn commits, and it's easier if rdoc can search actively for foo=
methods to show them as W attributes. This poses a problem though for
finding R attributes.

Paul

--
Student @ Eindhoven | JID: paul@luon.net
University of Technology, The Netherlands | email: paul@luon.net
>>> Using the Power of Debian GNU/Linux <<< | GnuPG: finger paul@luon.net

Dave Thomas

11/7/2004 12:58:00 PM

0


On Nov 7, 2004, at 3:16, Paul van Tilburg wrote:

>> rdoc --accessor foo ...
>
> Thanks, that works. However, I use a script to generate documentation
> on
> svn commits, and it's easier if rdoc can search actively for foo=
> methods to show them as W attributes. This poses a problem though for
> finding R attributes.

Not all xxx=() methods should be documented as attributes, though.


Cheers

Dave

James Britt

11/7/2004 2:06:00 PM

0

Dave Thomas wrote:
>
> On Nov 6, 2004, at 18:35, Gavin Kistner wrote:
>
>> And vice-versa...I frequently do something like:
>>
>> # The foo attribute
>> attr_accessor :foo
>> def foo=(n) #:nodoc:
>> #...special setter code necessary
>> end
>>
>> Specifically so that RDoc will document 'foo' as a RW attribute. The
>> downside of the above is that ruby complains about the redefinition of
>> #foo= if warnings are enabled.
>>
>> What I'm saying is that I'd like a way to tell RDoc to document a
>> certain method as an attribute.
>
>
> try
>
> rdoc --accessor foo ...

However, if someone simply runs rdoc on the source, the results won't be
the same (i.e., what in this case Gavin prefers)

And how can someone get
attr_reader :foo

to appear with the method definitions?


Thanks,

James

James Britt

11/7/2004 2:43:00 PM

0

Dave Thomas wrote:
>
> On Nov 7, 2004, at 3:16, Paul van Tilburg wrote:
>
>>> rdoc --accessor foo ...
>>
>>
>> Thanks, that works. However, I use a script to generate documentation on
>> svn commits, and it's easier if rdoc can search actively for foo=
>> methods to show them as W attributes. This poses a problem though for
>> finding R attributes.
>
>
> Not all xxx=() methods should be documented as attributes, though.

True. Rdoc should document methods as methods by default, however those
methods are defined.


James

Dave Thomas

11/7/2004 5:48:00 PM

0


On Nov 7, 2004, at 8:05, James Britt wrote:

> And how can someone get
> attr_reader :foo
>
> to appear with the method definitions?

Make it a method? :)

It seems to be that if you're trying to save typing by entering

attr_reader :foo

rather than

def foo; @foo; end

you're giving up a fair amount of clarity in your source to save 3
characters. If it's a method, why not make it a method?


Cheers

Dave

Sam Roberts

11/7/2004 6:26:00 PM

0

Quoteing dave@pragprog.com, on Mon, Nov 08, 2004 at 02:47:37AM +0900:
>
> On Nov 7, 2004, at 8:05, James Britt wrote:
>
> >And how can someone get
> > attr_reader :foo
> >
> >to appear with the method definitions?
>
> Make it a method? :)
>
> It seems to be that if you're trying to save typing by entering
>
> attr_reader :foo
>
> rather than
>
> def foo; @foo; end
>
> you're giving up a fair amount of clarity in your source to save 3
> characters. If it's a method, why not make it a method?

I agree with this, but the opposite is useful, and not possible to get
by changing the code.

What goes in the attrs section is decided by an implementation detail of
using attr_*, but if you have 3 "attributes", but 1 you have to
implement with some code (maybe it returns an object/information you
don't to want to create/calculate until necessary), it'll appear in the
methods section. Fair enough, but a reader doesn't care how I implement
my attributes, and having whats in the section be so arbitrary makes it
hard to find things, you never know what section it will be in when
consulting the docs.


Anyhow, I find it really useful to distinguish between attributes and
methods in documentation, even though its not a technical distinction,
its more of an "intention" distinction.


But... having the distinction decided only by an implementation detail
is a little frustrating, any chance of adding an :attr: attribute syntax
to docs, so that you can force a method into the attribute section?


Also, what about arbitrary sections! So you could decorate a method
with :section-Conversion Methods:, and it would go in a seperate section
from the other methods called Conversion Methods.


I love rdoc, but I could love it more...

Thanks!
Sam

James Britt

11/7/2004 7:26:00 PM

0

Dave Thomas wrote:

>
> On Nov 7, 2004, at 8:05, James Britt wrote:
>
>> And how can someone get
>> attr_reader :foo
>>
>> to appear with the method definitions?
>
>
> Make it a method? :)

I guess I've been under the impression that the attr_* methods did
actually create methods.

>
> It seems to be that if you're trying to save typing by entering
>
> attr_reader :foo
>
> rather than
>
> def foo; @foo; end
>
> you're giving up a fair amount of clarity in your source to save 3
> characters.

The example was short; in actual practice, there are often several
method names:

attr_reader :foo, :bar, :baz, :blug

So the savings on typing goes up.

I don't see what clarity I'm giving up in doing this.

> If it's a method, why not make it a method?

class Foo
attr_reader :bar
end
f = Foo.new
methods = f.methods - Object.methods
p methods # ["bar"]

Ruby seems to think I've defined a method.

If it's a method, why not document it as a method?

James

Paul van Tilburg

11/7/2004 8:55:00 PM

0

On Mon, Nov 08, 2004 at 03:26:09AM +0900, Sam Roberts wrote:
> Quoteing dave@pragprog.com, on Mon, Nov 08, 2004 at 02:47:37AM +0900:
> > you're giving up a fair amount of clarity in your source to save 3
> > characters. If it's a method, why not make it a method?
>
> I agree with this, but the opposite is useful, and not possible to get
> by changing the code.
>
> What goes in the attrs section is decided by an implementation detail of
> using attr_*, but if you have 3 "attributes", but 1 you have to
> implement with some code (maybe it returns an object/information you
> don't to want to create/calculate until necessary), it'll appear in the
> methods section. Fair enough, but a reader doesn't care how I implement
> my attributes, and having whats in the section be so arbitrary makes it
> hard to find things, you never know what section it will be in when
> consulting the docs.

Exactly, that was what I meant. But what is the best solution to this...
considering all foo=(arg) can't be the solution, however I can't think
of a time when you not mean this to mimic an attribute.

Paul

--
Student @ Eindhoven | JID: paul@luon.net
University of Technology, The Netherlands | email: paul@luon.net
>>> Using the Power of Debian GNU/Linux <<< | GnuPG: finger paul@luon.net