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
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/
I've started using it for my projects and I like it so far.
···
--
Posted via http://www.ruby-forum.com/\.
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).
···
On Jan 5, 2009, at 13:50 , davetron5000 wrote:
I realize specifying the types of things is not the Ruby way[...]
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?
···
On Jan 5, 6:31 pm, Suraj Kurapati <s...@gna.org> wrote:
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 YARDochttp://yard.rubyforge.org/
I've started using it for my projects and I like it so far.
--
Posted viahttp://www.ruby-forum.com/.
Ryan Davis 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
···
On Jan 5, 2009, at 13:50 , davetron5000 wrote:
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.
···
--
Posted via http://www.ruby-forum.com/\.
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:
···
On Jan 5, 2009, at 20:09 , Suraj Kurapati wrote:
% svn up ; ls -l lib/rdoc*
At revision 21353.
-rw-rw-r-- 1 ryan ryan 14089 Oct 25 15:15 lib/rdoc.rb
lib/rdoc:
total 296
-rw-rw-r-- 1 ryan ryan 8248 Jun 17 2008 README
-rw-rw-r-- 1 ryan ryan 24464 Sep 25 00:04 code_objects.rb
-rw-rw-r-- 1 ryan ryan 12146 Sep 25 00:04 diagram.rb
-rw-rw-r-- 1 ryan ryan 5179 Feb 18 2008 dot.rb
drwxrwxr-x 13 ryan ryan 442 Sep 25 00:04 generator
-rw-rw-r-- 1 ryan ryan 26794 Sep 25 00:04 generator.rb
-rw-rw-r-- 1 ryan ryan 2470 Sep 23 00:00 known_classes.rb
drwxrwxr-x 16 ryan ryan 544 Sep 25 00:04 markup
-rw-rw-r-- 1 ryan ryan 10270 Sep 25 00:04 markup.rb
-rw-rw-r-- 1 ryan ryan 16029 Sep 25 00:04 options.rb
drwxrwxr-x 8 ryan ryan 272 Dec 27 12:41 parser
-rw-rw-r-- 1 ryan ryan 3287 Dec 27 12:41 parser.rb
-rw-rw-r-- 1 ryan ryan 8291 Sep 25 00:04 rdoc.rb
drwxrwxr-x 12 ryan ryan 408 Jan 6 00:57 ri
-rw-rw-r-- 1 ryan ryan 72 Aug 9 19:38 ri.rb
-rw-rw-r-- 1 ryan ryan 1959 Aug 9 19:38 stats.rb
-rw-rw-r-- 1 ryan ryan 1519 Jun 17 2008 template.rb
-rw-rw-r-- 1 ryan ryan 676 Feb 18 2008 tokenstream.rb
rdoc is developed externally but continuously integrated into ruby-core. there have been no plans to remove rdoc from core.
···
On Jan 6, 2009, at 09:39 , Suraj Kurapati 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?