Forum: Ruby improvements to rdoc/alternatives

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
F74253f4a099258870157426b4cdb2dc?d=identicon&s=25 davetron5000 (Guest)
on 2009-01-05 22:56
(Received via mailing list)
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
Bc368ef524130e8d0deb386de961e24a?d=identicon&s=25 Suraj Kurapati (snk)
on 2009-01-06 00:30
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.
F74253f4a099258870157426b4cdb2dc?d=identicon&s=25 davetron5000 (Guest)
on 2009-01-06 03:24
(Received via mailing list)
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?
Bc368ef524130e8d0deb386de961e24a?d=identicon&s=25 Suraj Kurapati (snk)
on 2009-01-06 05:09
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.
5a837592409354297424994e8d62f722?d=identicon&s=25 Ryan Davis (Guest)
on 2009-01-06 10:11
(Received via mailing list)
On Jan 5, 2009, at 20:09 , Suraj Kurapati 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:
5a837592409354297424994e8d62f722?d=identicon&s=25 Ryan Davis (Guest)
on 2009-01-06 10:26
(Received via mailing list)
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).
F52a217f68b0d4db49ce2ceb06f79691?d=identicon&s=25 Alex Fenton (Guest)
on 2009-01-06 17:00
(Received via mailing list)
Ryan Davis 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
Bc368ef524130e8d0deb386de961e24a?d=identicon&s=25 Suraj Kurapati (snk)
on 2009-01-06 18:38
Ryan Davis wrote:
> On Jan 5, 2009, at 20:09 , Suraj Kurapati 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?
5a837592409354297424994e8d62f722?d=identicon&s=25 Ryan Davis (Guest)
on 2009-01-07 08:43
(Received via mailing list)
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?

rdoc is developed externally but continuously integrated into ruby-
core. there have been no plans to remove rdoc from core.
This topic is locked and can not be replied to.