Proper way to RDoc markup?

Ruby
1

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

2

Serg K. wrote:

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 W.

3

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

Thanks though.

4

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.

5

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

On Fri, Feb 15, 2008 at 3:30 PM, Serg K. [email protected] wrote:

That is:
attr_reader :y

Best regards,

Jari W.

–
http://www.jeremymcanally.com/

My books:
Ruby in Practice

My free Ruby e-book

My blogs:

http://www.rubyinpractice.com/

6

On Feb 15, 2008, at 5:28 PM, Jeremy McAnally wrote:

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 W.

7

I guess…? You just need to pay attention to what you’re doing. :stuck_out_tongue:
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

On Fri, Feb 15, 2008 at 4:17 PM, Serg K. [email protected] wrote:

puts b.to_s
On Feb 15, 2008, at 4:06 PM, Jeremy McAnally wrote:

Not quite what i wanted. I wanted to capture inline comments. i know

def x

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

–
http://www.jeremymcanally.com/

My books:
Ruby in Practice

My free Ruby e-book

My blogs:

http://www.rubyinpractice.com/

8

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

9

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? :wink:

–Jeremy

On Feb 15, 2008 5:42 PM, Gary W. [email protected] wrote:

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

Gary W.

–
http://jeremymcanally.com/
http://entp.com

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

Or, my blogs:

http://rubyinpractice.com

10

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 B. http://agileconsultingllc.com
[email protected]

11

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 W.

12

Serg K. wrote:

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