[lnkForumImage]
TotalShareware - Download Free Software
Confronta i prezzi di migliaia di prodotti.
Asp Forum
 Home | Login | Register | Search 


 

Forums >

comp.lang.ruby

Proper way to RDoc markup?

Serg Koren

2/15/2008 7:45:00 PM

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
11 Answers

Jari Williamsson

2/15/2008 8:06:00 PM

0

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

Serg Koren

2/15/2008 8:30:00 PM

0

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
>

Jeremy McAnally

2/15/2008 9:06:00 PM

0

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

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

My free Ruby e-book
http://www.humblelittlerub...

My blogs:
http://www.mrneigh...
http://www.rubyinpra...

Serg Koren

2/15/2008 9:17:00 PM

0

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.jeremymca...
>
> My books:
> Ruby in Practice
> http://www.manning.com...
>
> My free Ruby e-book
> http://www.humblelittlerub...
>
> My blogs:
> http://www.mrneigh...
> http://www.rubyinpra...
>

Jeremy McAnally

2/15/2008 10:29:00 PM

0

I guess...? You just need to pay attention to what you're doing. :P
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.jeremymca...
> >
> > My books:
> > Ruby in Practice
> > http://www.manning.com...
> >
> > My free Ruby e-book
> > http://www.humblelittlerub...
> >
> > My blogs:
> > http://www.mrneigh...
> > http://www.rubyinpra...
> >
>
>
>



--
http://www.jeremymca...

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

My free Ruby e-book
http://www.humblelittlerub...

My blogs:
http://www.mrneigh...
http://www.rubyinpra...

Gary Wright

2/15/2008 10:42:00 PM

0


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

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

2/16/2008 4:18:00 AM

0

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

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. :P
> > 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://jeremymca...
http:...

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

Or, my blogs:
http://mrneig...
http://rubyinpr...

Steve Ross

2/16/2008 4:47:00 AM

0

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? ;)
>
> --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. :P
>>> 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://jeremymca...
> http:...
>
> Read my books:
> Ruby in Practice (http://manning.com...)
> My free Ruby e-book (http://humblelittlerub...)
>
> Or, my blogs:
> http://mrneig...
> http://rubyinpr...
>

Jari Williamsson

2/16/2008 6:48:00 AM

0

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. :P
>> 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
>
>

Rob Biedenharn

2/18/2008 3:14:00 PM

0

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://agileconsult...
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? ;)
>
> --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. :P
>>> 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://jeremymca...
> http:...
>
> Read my books:
> Ruby in Practice (http://manning.com...)
> My free Ruby e-book (http://humblelittlerub...)
>
> Or, my blogs:
> http://mrneig...
> http://rubyinpr...