Proper way to RDoc markup?

[Serg Koren]

Hi,

I can't figure this out. Is there a way to inline markup an accessor
for Rdoc?

That is:

def x

attr_accessor :x # this is an X comment
attr_reader :y # this is a Y comment

end

I want the inline comments to show up in the Rdoc as part of the
attribute documentation.

Thanks

 

[Jari Williamsson]

I can't figure this out. Is there a way to inline markup an accessor
for Rdoc?

That is:

def x

attr_accessor :x # this is an X comment
attr_reader :y # this is a Y comment

end

I want the inline comments to show up in the Rdoc as part of the
attribute documentation.

# this is an X comment
attr_accessor :x
# this is a Y comment
attr_reader :y


Best regards,

Jari Williamsson

 

[Serg Koren]

Not quite what i wanted. I wanted to capture inline comments. i know
that I can capture standalone line comments.

Thanks though.

 

[Jeremy McAnally]

I don't think that's possible. Unless you want to hack on the RDoc
parser, that is.

What's the difference between what Jari offered and inline comments?

--Jeremy

Not quite what i wanted. I wanted to capture inline comments. i know
that I can capture standalone line comments.

Thanks though.

--
http://www.jeremymcanally.com/

My books:
Ruby in Practice
http://www.manning.com/mcanally/

My free Ruby e-book
http://www.humblelittlerubybook.com/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/

 

[Serg Koren]

hm oh well.

The difference is a matter of programming style. It makes it clear
that the comment is attached to the attribute. Also it keeps someone
from doing this


# this is an X comment
a = b * c
puts b.to_s
attr_reader :x


... sticking code between the comment and the object it belongs to.

Thanks tho.

 

[Jeremy McAnally]

I guess...? You just need to pay attention to what you're doing.
I personally think this is more readable than inlining:

# This does something fun
attr_reader :fun

# This does something writable
attr_accessor :read_write

# This does something AWESOME
attr_accessor :forty_two

--Jeremy

hm oh well.

The difference is a matter of programming style. It makes it clear
that the comment is attached to the attribute. Also it keeps someone
from doing this



# this is an X comment
a = b * c
puts b.to_s
attr_reader :x


... sticking code between the comment and the object it belongs to.

Thanks tho.

--
http://www.jeremymcanally.com/

My books:
Ruby in Practice
http://www.manning.com/mcanally/

My free Ruby e-book
http://www.humblelittlerubybook.com/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/

 

[Gary Wright]

I guess...? You just need to pay attention to what you're doing.
I personally think this is more readable than inlining:

# This does something fun
attr_reader :fun

# This does something writable
attr_accessor :read_write

# This does something AWESOME
attr_accessor :forty_two

Yuck, that is 8 lines vs. 3 (below). I always found it
strange that RDOC didn't parse comments to the right
of an accessor declaration yet that is exactly how
attributes are documented in the HTML pages generated
by RDOC.

attr_reader :fun # This does something fun
attr_accessor :read_write # This does something writable
attr_accessor :forty_two # This does something AWESOME


Gary Wright

 

[Jeremy McAnally]

I'd rather have really readable code and good generated documentation
than 5 LOC.

Of course, doing this often would throw off your app LOC to testing
LOC, now wouldn't it?

--Jeremy

Yuck, that is 8 lines vs. 3 (below). I always found it
strange that RDOC didn't parse comments to the right
of an accessor declaration yet that is exactly how
attributes are documented in the HTML pages generated
by RDOC.

attr_reader :fun # This does something fun
attr_accessor :read_write # This does something writable
attr_accessor :forty_two # This does something AWESOME


Gary Wright

--
http://jeremymcanally.com/
http://entp.com

Read my books:
Ruby in Practice (http://manning.com/mcanally/)
My free Ruby e-book (http://humblelittlerubybook.com/)

Or, my blogs:
http://mrneighborly.com
http://rubyinpractice.com

 

[s.ross]

Readability is in the eye of the beholder. To me, good inline
documentation is far more useful than long preambles because it's
right next to (or on top of) the relevant code. Classes and methods
that are prefaced by a ton of documentation feel like PHPDoc to me.
I'll have to agree with Gary on this one but not just because of LOC
-- because the proximity of the documentation to the code makes it
more relevant. It also makes it more likely that I'll change the
comment if I change the code.

-s

 

[Jari Williamsson]

Perhaps a reason for RDoc not supporting inline documentation for
attributes is that it can't safely judge how to interpret multiline
inline comments.

attr_accessor :my_accessor # This accessor will do something, but
# this row could belong to any of the accessors because of the new line
attr_accessor :my_next_accessor


Best regards,

Jari Williamsson

 

[Rob Biedenharn]

Well, if you take a look at vendor/rails/railties/lib/code_statistics.rb

while line = f.gets
stats["lines"] += 1
stats["classes"] += 1 if line =~ /class [A-Z]/
stats["methods"] += 1 if line =~ /def [a-z]/
stats["codelines"] += 1 unless line =~ /^\s*$/ || line =~ /^
\s*#/
end

You'll see that both forms will be counted as 3 LOC since the blank
and comment-only lines are not counted as 'codelines'.

-Rob

Rob Biedenharn http://agileconsultingllc.com
(e-mail address removed)

 

[Tony Strauss]

def x

attr_accessor :x # this is an X comment
attr_reader :y # this is a Y comment

end

I want the inline comments to show up in the Rdoc as part of the
attribute documentation.

That sounds very reasonable. If you would, please add an enhancement
request to:
http://rubyforge.org/tracker/?atid=2475&group_id=627&func=browse