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
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.
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.
try
rdoc --accessor foo ...
Cheers
Dave
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
endSpecifically 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.
>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
On Sun, Nov 07, 2004 at 12:36:40PM +0900, Dave Thomas wrote:
On Nov 6, 2004, at 18:35, Gavin Kistner wrote:
--
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 wrote:
And vice-versa...I frequently do something like:
# The foo attribute
attr_accessor :foo
def foo=(n) #:nodoc:
#...special setter code necessary
endSpecifically 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
On Nov 6, 2004, at 18:35, Gavin Kistner wrote:
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
On Nov 6, 2004, at 8:36 PM, Dave Thomas wrote:
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 ...
--
(-, /\ \/ / /\/
Not all xxx=() methods should be documented as attributes, though.
Cheers
Dave
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.
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
On Nov 7, 2004, at 8:05, James Britt wrote:
And how can someone get
attr_reader :footo appear with the method definitions?
Quoteing gavin@refinery.com, on Mon, Nov 08, 2004 at 09:56:28AM +0900:
>>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 ...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
On Nov 6, 2004, at 8:36 PM, Dave Thomas wrote:
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 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
On Nov 7, 2004, at 3:16, Paul van Tilburg wrote:
Quoteing dave@pragprog.com, on Mon, Nov 08, 2004 at 02:47:37AM +0900:
>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
On Nov 7, 2004, at 8:05, James Britt wrote:
Dave Thomas wrote:
And how can someone get
attr_reader :footo 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
On Nov 7, 2004, at 8:05, James Britt wrote:
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
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.
--
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
Quoteing jamesUNDERBARb@neurogami.com, 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
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
On Nov 7, 2004, at 13:26, James Britt wrote:
> 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.
Quoteing paul@luon.net, on Mon, Nov 08, 2004 at 05:55:11AM +0900:
> 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...
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
On Mon, Nov 08, 2004 at 03:26:09AM +0900, Sam Roberts wrote:
Sam Roberts wrote:
Quoteing jamesUNDERBARb@neurogami.com, 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
Dave Thomas wrote:
> 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
On Nov 7, 2004, at 13:26, James Britt wrote:
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
On Nov 7, 2004, at 17:37, James Britt wrote:
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.
Quoteing jamesUNDERBARb@neurogami.com, on Mon, Nov 08, 2004 at 08:37:33AM +0900:
Sam Roberts wrote:
>Quoteing jamesUNDERBARb@neurogami.com, 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!
>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.
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