[RDOC] Documenting accessor methods as methods

[James Britt]

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

 

[Gavin Kistner]

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]

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]

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

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
[/QUOTE]

 

[Dave Thomas]

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]

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]

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]

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]

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 02:47:37AM +0900:

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]

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]

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 02:47:37AM +0900:

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
[/QUOTE]

 

[Sam Roberts]

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 04:26:26AM +0900:

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?

By this definition, there is no such thing as an attribute, only
methods.

Ruby has a syntactic short-cut for defining these kinds of methods.

rdoc has a documentation convention of documenting methods defined using
this short-cut differently from other methods.

Sam

 

[Sam Roberts]

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 05:55:11AM +0900:

Exactly, that was what I meant. But what is the best solution to this...

I think it is to use the rdoc attributes, the # :..: thingies that can
appear after a method definition.

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.

Cheers,
Sam

 

[James Britt]

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 04:26:26AM +0900:

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?

By this definition, there is no such thing as an attribute, only
methods.

That is my understanding of Ruby. I may be wrong.

(I take the view that 'attributes' are a private aspect of an object,
and that all object access (barring reflection, et al) occurs via
messages. I'm one of those who see "@foo" and read it as, "the
attribute foo." "attr_reader :foo " creates a method to access this
attribute, @foo. I know from prior discussions that this is likely a
minority view. )

Ruby has a syntactic short-cut for defining these kinds of methods.

Right. I see this as a developer convenience for creating methods. An
implementation detail, not an expression of intent that should be
exposed in the API documentation.

rdoc has a documentation convention of documenting methods defined using
this short-cut differently from other methods.

This is the issue. I understand that many, maybe most, like to think of
Ruby as having almost-but-not-really public instance variables, AKA
'attributes'.

I understand why some, maybe most, might want to document some methods
as though they were public instance variables. I would just prefer that
this was not baked into the documentation tool. Or least that there be
a way to opt out of this using some in-code markup.

As it is, developers who want to use the short form to define attribute
accessor methods have to accept that the documentation will refer to
these methods as something other than methods.


James

 

[Gavin Kistner]

try

rdoc --accessor foo ...

Well, hell. RTFM, eh? That'll work for now.

Still, it's not a great solution, because it means that I need to
create and save an rdoc shell script specifying the accessor methods,
so that I can re-run rdoc on updates. It would be nicer to be able to
include the directive in rdoc-type comments in the source code itself.

Thanks for the quick response (and RDoc, and...well, a lot in general

 

[Dave Thomas]

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.

James:

I probably wrote the book that gave you you this information: I really
don't need you telling me back

If the distinction between attributes and methods is significant to
you, then you are losing clarity in your code by using attributes when
you want them documented as methods. That is, you want the users of
your documentation to think of these things as methods, but you don't
care that readers of the code will see them as attributes. That feels
sloppy to me, and that's why I asked why you wouldn't want to type them
in as methods.


Cheers

Dave

 

[Dave Thomas]

Right. I see this as a developer convenience for creating methods.
An implementation detail, not an expression of intent that should be
exposed in the API documentation.

That's where we differ, and why RDoc distinguishes between attr and
regular method definitions. It isn't just a macro facility: it's an
expression of intent.

We had this discussion before--attributes are not the same as instance
variables. I never convinced you then, and I suspect I won't now.

Sam has raised some good points, though, and I may see if I can warp
the internals enough to handle :attr: modifiers.

Cheers

Dave

 

[Sam Roberts]

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 09:56:28AM +0900:

Well, hell. RTFM, eh? That'll work for now.

The problem with things always getting better is you don't always
know about the new goodness. I'll try that.

Still, it's not a great solution, because it means that I need to
create and save an rdoc shell script specifying the accessor methods,

Yep, and I'd like the info in the source, but still, I generate my docs
from a makefile, it'll work.

Cheers,
Sam

 

[Sam Roberts]

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 08:37:33AM +0900:

Quoteing (e-mail address removed), on Mon, Nov 08, 2004 at 04:26:26AM
+0900:

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?

By this definition, there is no such thing as an attribute, only
methods.

That is my understanding of Ruby. I may be wrong.

Not sure. If it's your understanding that all attributes are methods,
then you are right.

If you are of the understanding that there are no attributes, you are
wrong, an attribute is a method defined with attr_*, etc., as you
demonstrate above.

(I take the view that 'attributes' are a private aspect of an object,
and that all object access (barring reflection, et al) occurs via
messages. I'm one of those who see "@foo" and read it as, "the
attribute foo." "attr_reader :foo " creates a method to access this
attribute, @foo. I know from prior discussions that this is likely a
minority view. )

It's a reasonable view. There's lots of differing definitions of object,
attribute, function, etc., and that can be yours. But, if you don't use
the definitions customary with the language you're working with, nobody
will know what you're talking about!

Right. I see this as a developer convenience for creating methods. An
implementation detail, not an expression of intent that should be
exposed in the API documentation.

Ah, and there we differ. It's quite useful, IMO, to think of objects in
terms of set/get APIs (aka "attributes"), and APIs that do things. That
Ruby implements all of these as methods is cool, but its still useful to
explain some of my classes to PEOPLE in terms of the distinction, even
if the ruby interpreter doesn't see a distinction.

As it is, developers who want to use the short form to define attribute
accessor methods have to accept that the documentation will refer to
these methods as something other than methods.

There's a good chance you can play some games with alias to make new
names for attr_* and friends, and that that would fool rdoc, and still
give you convenience.

For that matter, you could just write your own code that takes a
variable list of symbols and defines a bunch of methods. I'm not good
enough with this stuff to type out a solution off the top of my head,
but I don't think there's anything attr_reader does that you can't
implement yourself, getting both the convenience, and getting them
doc'ed as you like, and not confusing readers of your code who might
share the more common community view of what an attribute is.

Have fun,
Sam

 

[James Britt]

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.

James:

I probably wrote the book that gave you you this information: I really
don't need you telling me back

Yes: and no doubt that's true. You also know I reviewed that part of
the book, and know what I think, so the round-about suggestion of
writing out methods was equally unnecessary. Perhaps you meant well,
but it struck me as condescending.

Anyway, I gather that rdoc will not do what I want.

If the distinction between attributes and methods is significant to you,
then you are losing clarity in your code by using attributes when you
want them documented as methods. That is, you want the users of your
documentation to think of these things as methods, but you don't care
that readers of the code will see them as attributes. That feels sloppy
to me, and that's why I asked why you wouldn't want to type them in as
methods.

Well, that's the disconnect, and as you've noted elsewhere, we've had
this discussion before, and neither has found the other convincing. I
know your position on this, I know this is built into rdoc, I think I
understand the motivation. I just don't share that view of attribute
accessor methods.

I simply wanted to know how I can get these methods documented as
methods, rather than as something else, while using the short-hand
notation. If rdoc doesn't offer this choice, then simply saying so
would have sufficed.

I want users of the code to think of method as methods. Readers of the
code are going to think what they want. It may very well be that they
view certain methods as something other than methods, but writing out
the method long-hand, when all it does is read or write to something
that begins with the 'at' symbol, is not going to mean much to someone
who views Ruby's object model differently than I do. I disagree that
using attr_* means anything other than that I'm too lazy to type.

I gather there is enough cultural momentum that this notion of public
properties (a la Java, perhaps) is the norm. I think this complicates
thinking about Ruby, but that's my problem.

I just wanted to know if something was possible. Although no one has
yet to say so, I suspect that it isn't.


Thanks,


James