From: davetron5000 <davetron5000@...>
Date: 2009-01-06T06:50:03+09:00
Subject: improvements to rdoc/alternatives

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