Proper way to RDoc markup?

ruby-talk
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 Koren wrote:

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

3

Serg Koren 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

···

--
Posted via http://www.ruby-forum.com/\.

4

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

Thanks though.

···

On Feb 15, 2008, at 3:06 PM, Jari Williamsson wrote:

Serg Koren wrote:

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

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 Koren <skoren@comcast.net> wrote:

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

Thanks though.

On Feb 15, 2008, at 3:06 PM, Jari Williamsson wrote:

> Serg Koren wrote:
>> 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
>

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

My books:
Ruby in Practice

My free Ruby e-book

My blogs:

http://www.rubyinpractice.com/

6

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.

···

On Feb 15, 2008, at 4:06 PM, Jeremy McAnally wrote:

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 Koren <skoren@comcast.net> > wrote:

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

Thanks though.

On Feb 15, 2008, at 3:06 PM, Jari Williamsson wrote:

Serg Koren wrote:

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

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

My books:
Ruby in Practice
Ruby in Practice

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

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

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 Koren <skoren@comcast.net> wrote:

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.

On Feb 15, 2008, at 4:06 PM, Jeremy McAnally wrote:

> 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 Koren <skoren@comcast.net> > > wrote:
>> Not quite what i wanted. I wanted to capture inline comments. i know
>> that I can capture standalone line comments.
>>
>> Thanks though.
>>
>> On Feb 15, 2008, at 3:06 PM, Jari Williamsson wrote:
>>
>>> Serg Koren wrote:
>>>> 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
>>>
>>
>>
>>
>
>
>
> --
> http://www.jeremymcanally.com/
>
> My books:
> Ruby in Practice
> Ruby in Practice
>
> My free Ruby e-book
> http://www.humblelittlerubybook.com/
>
> 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

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

···

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

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

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 Wright <gwtmp01@mac.com> wrote:

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

> 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

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://rubyinpractice.com

10

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

Gary Wright wrote:

···

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

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

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

11

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

···

On Feb 15, 2008, at 8:17 PM, Jeremy McAnally wrote:

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 Wright <gwtmp01@mac.com> wrote:

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

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

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

12

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
Rob@AgileConsultingLLC.com

···

On Feb 15, 2008, at 11:17 PM, Jeremy McAnally wrote:

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 Wright <gwtmp01@mac.com> wrote:

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

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

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