improvements to rdoc/alternatives

[davetron5000]

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

 

[Suraj Kurapati]

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.

 

[davetron5000]

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?

 

[Suraj Kurapati]

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.

 

[Ryan Davis]

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:

 

[Ryan Davis]

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).

 

[Alex Fenton]

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

 

[Suraj Kurapati]

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?

 

[Ryan Davis]

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.