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
Nope. Debatable, perhaps. But it's the way I intended it.
Dave
···
On Dec 31, 2006, at 8:26 PM, Daniel Berger wrote:
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?
Dave Thomas wrote:
> 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
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
···
On Dec 31, 2006, at 8:26 PM, Daniel Berger wrote:
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
Rob@AgileConsultingLLC.com
···
On Dec 31, 2006, at 9:55 PM, Dave Thomas wrote:
On Dec 31, 2006, at 8:26 PM, Daniel Berger wrote:
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
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
···
On Dec 31, 2006, at 9:40 PM, Daniel Berger wrote:
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.
He's not. He's referring to automatic links in comments.
···
On Jan 2, 2007, at 13:18, Rob Biedenharn wrote:
On Dec 31, 2006, at 9:55 PM, Dave Thomas wrote:
On Dec 31, 2006, at 8:26 PM, Daniel Berger wrote:
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.
Perhaps you're looking for the #:nodoc: tag that stops a method (or constant or class) from being included in the output:
--
Eric Hodel - drbrain@segment7.net - http://blog.segment7.net
I LIT YOUR GEM ON FIRE!
Dave Thomas wrote:
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...
Dave Thomas wrote:
> 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'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
···
On Dec 31, 2006, at 9:40 PM, Daniel Berger wrote: