# Question on rdoc, unwanted hyperlinked methods **URL:** \ **Category:** Ruby\ **Created:** [January 1, 2007, 3:28am UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882 "2007-01-01T03:28:34Z")\ **Posts on this page:** 8\ **Page:** 1
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 1, 2007, 3:28am UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/1 "2007-01-01T03:28:34Z")
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 ---
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 1, 2007, 3:56am UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/2 "2007-01-01T03:56:36Z")
On Dec 31, 2006, at 8:26 PM, Daniel B. 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 ---
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 1, 2007, 4:40am UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/3 "2007-01-01T04:40:41Z")
Dave T. wrote: > On Dec 31, 2006, at 8:26 PM, Daniel B. 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 ---
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 1, 2007, 8:41pm UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/4 "2007-01-01T20:41:59Z")
Dave T. 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… ---
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 1, 2007, 3:31pm UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/5 "2007-01-01T15:31:20Z")
On Dec 31, 2006, at 9:40 PM, Daniel B. 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 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 ---
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 2, 2007, 10:20pm UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/6 "2007-01-02T22:20:12Z")
On Dec 31, 2006, at 9:55 PM, Dave T. wrote: > On Dec 31, 2006, at 8:26 PM, Daniel B. 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 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 B. [http://agileconsultingllc.com](http://agileconsultingllc.com) removed\_email\_address@domain.invalid ---
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 3, 2007, 5:01pm UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/7 "2007-01-03T17:01:08Z")
Dave T. wrote: > 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 ---
**Author:** ![danielb](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/c57346/32.png) [@danielb](https://www.ruby-forum.com/u/danielb)\ **Post date:** [January 2, 2007, 11:34pm UTC](https://www.ruby-forum.com/t/question-on-rdoc-unwanted-hyperlinked-methods/80882/8 "2007-01-02T23:34:27Z")
On Jan 2, 2007, at 13:18, Rob B. wrote: > constant or class) from being included in the output: > He’s not. He’s referring to automatic links in comments. – Eric H. - removed\_email\_address@domain.invalid - [http://blog.segment7.net](http://blog.segment7.net) I LIT YOUR GEM ON FIRE!