Question on rdoc, unwanted hyperlinked methods

[Daniel Berger]

Hi all,

Ruby 1.8.5

I thought you had to specially mark or tag methods in order for them to
be hyperlinked. However, it seems that a comment that contains a plain
word that happens to match a method name is hyperlinked to that method.
For example:

class Foo
# This is a test constant
XXX = 99

# I just want to use the word test here without it becoming a hyperlink
def test
puts "Hello"
end
end

The word 'test' in both cases ends up hyperlinked to the test method,
even though I don't want it to. It thought you had to write it as
Foo#test, or use 'link:', in order to get a hyperlink like that. Is this
a bug?

Regards,

Dan

 

[Dave Thomas]

The word 'test' in both cases ends up hyperlinked to the test
method, even though I don't want it to. It thought you had to
write it as Foo#test, or use 'link:', in order to get a hyperlink
like that. Is this a bug?

Nope. Debatable, perhaps. But it's the way I intended it.


Dave

 

[Daniel Berger]

Nope. Debatable, perhaps

It's not clear in the documentation (Programming Ruby 2nd ed., p. 204)
that this is what the behavior is, unless I've missed it. I've always
written Foo#test if I wanted a method explicitly hyperlinked, because I
thought you had to. And, now that I see what the current behavior is,
I think I would prefer that explicit hyperlinking be required.

But it's the way I intended it.

Well, I guess I'll have to live with it then I suppose, since some
people may be expecting it at this point, but I'd definitely be curious
to see what other people think.

Regards,

Dan

 

[Dave Thomas]

It's not clear in the documentation (Programming Ruby 2nd ed., p. 204)
that this is what the behavior is, unless I've missed it. I've always
written Foo#test if I wanted a method explicitly hyperlinked,
because I
thought you had to. And, now that I see what the current behavior is,
I think I would prefer that explicit hyperlinking be required.

The underlying philosophy of the RDoc markup is that it should be
transparent. It was a reaction to JavaDoc, where you had to seriously
mess with your comments to make them work with the documentation
system. I wanted RDoc to be such that some third party reading the
original source didn't know that the comments were in a format
suitable for RDoc--I wanted the comments in the source to be written
for humans, not for the documentation tool.

As a result, RDoc contains lots of heuristics. If it gets it wrong
every now and then, I personally think that's an OK tradeoff.


Cheers


Dave

 

[S. Robert James]

The underlying philosophy of the RDoc markup is that it should be
transparent... I wanted RDoc to be such that some third party reading the
original source didn't know that the comments were in a format
suitable for RDoc... As a result, RDoc contains lots of heuristics. If it gets it wrong
every now and then, I personally think that's an OK tradeoff.

+1
I really enjoy this about RDoc.

Docs are primarily a tool for development. Their first requirment is
to be accurate and up to date. That only happens when they're trivial
to change. If you need to spend time marking them up, you'll wait
until you've completed the project to do so.

To me, this is all about enabling Agile development, in line with
Ruby's philosophy.

I would add that to publish end user distributable API docs, a tool
that is about more formal and controlled, like javadoc, is warranted.
Alas, there are very few Ruby project that are mature enough to have
that problem...

 

[Rob Biedenharn]

Nope. Debatable, perhaps. But it's the way I intended it.

Dave

Perhaps you're looking for the #:nodoc: tag that stops a method (or
constant or class) from being included in the output:

class Foo
# This is a test constant
XXX = 99 #:nodoc:

# I just want to use the word test here without it becoming a
hyperlink
def test #:nodoc:
puts "Hello"
end
end

Of course, you could just:
class Foo #:nodoc:
...
end
to stop rdoc generation for the whole Foo class.

-Rob

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

 

[Eric Hodel]

Perhaps you're looking for the #:nodoc: tag that stops a method (or
constant or class) from being included in the output:

He's not. He's referring to automatic links in comments.

 

[Daniel Berger]

The underlying philosophy of the RDoc markup is that it should be
transparent. It was a reaction to JavaDoc, where you had to seriously
mess with your comments to make them work with the documentation
system

I'm not familiar with JavaDoc, but I can imagine.

I wanted RDoc to be such that some third party reading the
original source didn't know that the comments were in a format
suitable for RDoc--I wanted the comments in the source to be written
for humans, not for the documentation tool.

Except that, to me, having to write "Class#method" in order to force an
html link in RDoc doesn't strike me as being out of line with your
philosophy of transparency. It's a standard way of referring to
instance methods these days, and it's quite readable IMO. No special
markup required.

As a result, RDoc contains lots of heuristics. If it gets it wrong
every now and then, I personally think that's an OK tradeoff.

I'm certainly not going to lose sleep over it. It's a minor nit,
really. I just happened to think that a minor bit of required
explicitness would generate better results without any real loss of
transparency.

Regards,

Dan