# Improvements to rdoc/alternatives **URL:** \ **Category:** Ruby\ **Created:** [January 5, 2009, 10:56pm UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972 "2009-01-05T22:56:42Z")\ **Posts on this page:** 9\ **Page:** 1
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 5, 2009, 10:56pm UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/1 "2009-01-05T22:56:42Z")
I love rdoc, but miss a few things from javadoc, namely the ability to specify the types of variables and returns as well as the cross- reference/link to standard library or other third-party libs. I realize specifying the types of things is not the Ruby way, but it would be nice to be able to do something like # frobnosticates the input parameters # # @param input either an IO or a String (which is assumed to be a filename) # @param num\_frobs an int # @param options for the frobbing # @option :size the size # @option :date the date # @option :some\_other\_option whatever # @return a Hash of the frobnosticated output # @raises FileNotFoundError if input couldn’t be found def frobnosticate(input,num\_frobs,options={}) do\_whatever() end And have “IO”, “String”, “int”, “Hash” and “FileNotFoundError” link to the the rdoc of where they came from (assuming rdoc was given this necessary information to make this link). I guess I’d like to have rdoc describe the aspects of the method with a bit more specificity. Is this something rdoc aspires to someday, or is this just not the “ruby way” of documenting? Dave ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 6, 2009, 12:30am UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/2 "2009-01-06T00:30:48Z")
davetron5000 wrote: > I love rdoc, but miss a few things from javadoc, namely the ability to > specify the types of variables and returns as well as the cross- > reference/link to standard library or other third-party libs. Try YARDoc [http://yard.rubyforge.org/](http://yard.rubyforge.org/) I’ve started using it for my projects and I like it so far. ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 6, 2009, 3:24am UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/3 "2009-01-06T03:24:07Z")
Yeah, that is what I’m looking for. I guess part 2 of my question is that given that RDoc is so prolific, what are the chances that rdoc will embrace some of these additional features so that most ruby libraries can take advantage of this? ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 6, 2009, 5:09am UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/4 "2009-01-06T05:09:53Z")
davetron5000 wrote: > Yeah, that is what I’m looking for. I guess part 2 of my question is > that given that RDoc is so prolific, what are the chances that rdoc > will embrace some of these additional features so that most ruby > libraries can take advantage of this? Although RDoc remains the de-facto API documentation tool for Ruby, it is no longer a part of the core Ruby distribution. It’s just another project; there’s nothing blessed or official about it. So I ask you: why not simply embrace YARDoc (which already supports all RDoc syntax) and leave RDoc behind? YARDoc does everything that we want, so let’s use and improve the tool that best suits our purpose. ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 6, 2009, 10:11am UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/5 "2009-01-06T10:11:14Z")
On Jan 5, 2009, at 20:09 , Suraj K. wrote: > Although RDoc remains the de-facto API documentation tool for Ruby, it > is no longer a part of the core Ruby distribution. It’s just another > project; there’s nothing blessed or official about it. huh? no… not true in the slightest: ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 6, 2009, 10:26am UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/6 "2009-01-06T10:26:37Z")
On Jan 5, 2009, at 13:50 , davetron5000 wrote: > I realize specifying the types of things is not the Ruby way[…] No, it really isn’t. I think it is fair to say that rdoc won’t being going that direction (via the maintainers at least). ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 6, 2009, 5:00pm UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/7 "2009-01-06T17:00:59Z")
Ryan D. wrote: > On Jan 5, 2009, at 13:50 , davetron5000 wrote: > > > I realize specifying the types of things is not the Ruby way[…] > > No, it really isn’t. I think it is fair to say that rdoc won’t being > going that direction (via the maintainers at least). It’s a pity if duck-typing has become such rigid dogma. Applied to RDoc, it ignores the fact that many useful libraries are extensions where class-based typing is unavoidable, because their Ruby objects are proxies for strongly typed pointers in another language (eg C++, Java). For these, class-type info is an important part of the method documentation. I was pleased to learn about YARDoc, having made do with a mess of hand-rolled Textile to overcome just this deficiency in RDoc. a ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 7, 2009, 8:43am UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/8 "2009-01-07T08:43:44Z")
On Jan 6, 2009, at 09:39 , Suraj K. wrote: > I thought that because RDoc 2.2.x is released as a gem, it had been > separated from ruby-core in order to evolve independently. Were there > plans to merge RDoc 2.x back into ruby-core? rdoc is developed externally but continuously integrated into ruby- core. there have been no plans to remove rdoc from core. ---
**Author:** ![davetron5000](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/a3d4f5/32.png) [@davetron5000](https://www.ruby-forum.com/u/davetron5000)\ **Post date:** [January 6, 2009, 6:38pm UTC](https://www.ruby-forum.com/t/improvements-to-rdoc-alternatives/156972/9 "2009-01-06T18:38:10Z")
Ryan D. wrote: > On Jan 5, 2009, at 20:09 , Suraj K. wrote: > > > Although RDoc remains the de-facto API documentation tool for Ruby, it > > is no longer a part of the core Ruby distribution. It’s just another > > project; there’s nothing blessed or official about it. > > huh? no… not true in the slightest: I thought that because RDoc 2.2.x is released as a gem, it had been separated from ruby-core in order to evolve independently. Were there plans to merge RDoc 2.x back into ruby-core?