rdoc/attributes

[Patrick Gundlach]

Hello out there,

I have a lot of get/set methods that take some complex data structure.
They behave like attributes. Now I would like to use rdoc
so that these methods appear in the attributes section (just like the
ones created with attr_accessor et al.) but are not defined with
attr_accessor, because Ruby gives me lots of warnings about redefining
the method.

So now I have:

class Foo

# Bar is very important
attr_accessor :bar

# Baz is crazy
attr_accessor :baz

def bar= (obj) #:nodoc:
...
end
def bar #:nodoc:
# calculate
return @complex_data_structure
end

def baz= (obj) #:nodoc:
...
end
def baz #:nodoc:
...
end
end

Running rdoc gives me something like

Attributes
-----------
bar [RW] Bar is very important
baz [RW] Baz is crazy


which is exactly what I want, but I would like to avoid creating dummy
methods with attr_accessor for some of the attributes. How can I tell
rdoc to write my methods as attributes? Or perhaps to tell ruby to
ignore those attr_accessor calls? =begin =end does not seem to work
(rdoc refuses to go through that section). Same with "if false ....
end".


Patrick

 

[Lothar Scholz]

Hello Patrick,

PG> ones created with attr_accessor et al.) but are not defined with
PG> attr_accessor, because Ruby gives me lots of warnings about redefining
PG> the method.

PG> So now I have:

PG> class Foo

PG> # Bar is very important
PG> attr_accessor :bar

PG> # Baz is crazy
PG> attr_accessor :baz

Add a "$VERBOSE = false" here

PG> def bar= (obj) #:nodoc:
PG> ...
PG> end
PG> def bar #:nodoc:
PG> # calculate
PG> return @complex_data_structure
PG> end

PG> def baz= (obj) #:nodoc:
PG> ...
PG> end
PG> def baz #:nodoc:
PG> ...
PG> end
PG> end

And a "$VERBOSE = true" here.
Maybe save value in another global variable like $OLD_VERBOSE and
restore from there.

This hides the duplication messages. Don't know about another
solution. Maybe in the future we can add the disabling of individual
warnings as we can in every C compiler.

 

[Joel VanderWerf]

Hello out there,

I have a lot of get/set methods that take some complex data structure.
They behave like attributes. Now I would like to use rdoc
so that these methods appear in the attributes section (just like the
ones created with attr_accessor et al.) but are not defined with
attr_accessor, because Ruby gives me lots of warnings about redefining
the method.

$ rdoc -A documented_accessor=RW
$ cat accessors.rb
class Foo

def self.documented_accessor(*args); end

# Bar is very important
documented_accessor :bar

# Baz is crazy
documented_accessor :baz

def bar= (obj) #:nodoc:

end
def bar #:nodoc:
# calculate
return @complex_data_structure
end

def baz= (obj) #:nodoc:

end
def baz #:nodoc:

end
end

And this produces exactly the output you want:

 

[Joel VanderWerf]

$ rdoc -A documented_accessor=RW

On second thought, maybe calling this class method
"document_as_accessor" would be nicer. The name can be anything you
want, as long as it doesn't conflict with other class methods.

 

[Patrick Gundlach]

[...]

$ rdoc -A documented_as_accessor=RW

def self.documented_as_accessor(*args); end

# Bar is very important
documented_as_accessor :bar

Yes, that rocks! Thanks Joel,

Patrick

 

[Lothar Scholz]

Hello Patrick,


PG> [...]


PG> Yes, that rocks! Thanks Joel,

Dammed, and it makes the life for tool writers much much harder.
I really hate this ruby hacks. So there is no standard way to generate
rdoc - this is far from good. Not everything that works is a well engineered
solution.

 

[Joel VanderWerf]

Hello Patrick,


PG> [...]




PG> Yes, that rocks! Thanks Joel,

Dammed, and it makes the life for tool writers much much harder.
I really hate this ruby hacks. So there is no standard way to generate
rdoc - this is far from good. Not everything that works is a well engineered
solution.

Why do you care _how_ the rdoc is generated? Can't you let rdoc do its
thing, generating to ri format, and load the resulting yaml? (Or maybe
even use the rdoc api.)

I probably don't understand what kind of tool functionality you have in
mind.

 

[Lothar Scholz]

Hello Joel,

JV> Why do you care _how_ the rdoc is generated? Can't you let rdoc do its
JV> thing, generating to ri format, and load the resulting yaml? (Or maybe
JV> even use the rdoc api.)

JV> I probably don't understand what kind of tool functionality you have in
JV> mind.

I'm working on RI/RDOC integration for the last two month. So this is just
a point that makes some of my ideas questionable.

First the good news, there is no problem when you use RubyGems. In the
Gem specification you can define how rdoc should be called for a gem.


But i see two problems:

a) how should a navigation tool window in an editor find out what
are attributes if this can be differently defined (possible different
for each file) ? It's already only possible based on heuristics but with
"attr_accessor" this works fine in most cases.
This is a problem for Eclipse, FreeRide and ArachnoRuby and i think also for
other editors like Zeus that use ctags.

b) in ArachnoRuby you can simply add a library to the project file
manager. Then the source directory tree appears in the file browser.
As the RI database must be defined on a project level (i explained
this in earlier posts) the RI data must be generated at this time.
But this is not longer possible as it is unkown how to do this.


One method to fix it is to add one more configuration option,
but this is not really what people want to see, they want something that
works out of the box. At least for this basic features and i think
RI/RDOC is a basic feature.

 

[Patrick Gundlach]

not directly related to your post, but anyway:


I'd wish that rdoc supports some dummy section such as

if false

# doc for foo
attr_accessor :foo

# doc for bar
def bar

end

so that ruby does not look at it, but rdoc does. This would make my
life more easy

Patrick

 

[Eric Hodel]

not directly related to your post, but anyway:

I'd wish that rdoc supports some dummy section such as

if false

# doc for foo
attr_accessor :foo

# doc for bar
def bar

end

so that ruby does not look at it, but rdoc does. This would make my
life more easy

http://rubyforge.org/tracker/?atid=2475&group_id=627&func=browse

Is where to put it.

 

[Patrick Gundlach]

Hello Eric,

http://rubyforge.org/tracker/?atid=2475&group_id=627&func=browse

Is where to put it.

Thanks for the pointer, it is there now.

Patrick