Forum: Ruby rdoc 2.4.0 Released

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.
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2009-02-25 07:04
(Received via mailing list)
rdoc version 2.4.0 has been released!

* <Project Page: http://rubyforge.org/projects/rdoc/>
* <Documentation: http://rdoc.rubyforge.org/>

RDoc is an application that produces documentation for one or more
Ruby source files.  RDoc includes the +rdoc+ and +ri+ tools for
generating and displaying online documentation.

At this point in time, RDoc 2.x is a work in progress and may incur
further API changes beyond what has been made to RDoc 1.0.1.  Command-
line tools are largely unaffected, but internal APIs may shift rapidly.

See RDoc for a description of RDoc's markup and basic use.

Changes:

### 2.4.0 / 2009-02-24

* 9 Minor Enhancements
   * `ri -f html` is now XHTML-happy
   * Clarified RDoc::Markup link syntax.  Bug #23517 by Eric Armstrong.
   * Number of threads to parse with is now configurable
   * Darkfish can now use alternate templates from $LOAD_PATH via -T
   * Removed F95 parser in favor of the rdoc-f95 gem
   * Moved HTML and XML generators to unmaintained
     * No gem will be provided as it's too difficult to make them work
     * Removed options --one-file, --style=, --inline-source, --
promiscuous,
       --op-name
   * Removed support for --accessor, use regular documentation or
     the method directive instead.  See RDoc::Parser::Ruby
   * Removed --ri-system as it is unused by Ruby's makefiles
   * Added method list to index.html

* 6 Bug Fixes
   * nodoc'd classes no longer appear in the index.  Bug #23751 by
Clifford
     Heath.
   * Fix 1.9 compatibility issues.  Bug #23815 by paddor.
   * Darkfish now respects --charset
   * RDoc no longer attempts to be lazy when building HTML.  This is a
     workaround.  Bug #23893 by Stefano Crocco.
   * RDoc doesn't crash with def (blah).foo() end
   * RDoc doesn't crash with #define functions

* <Project Page: http://rubyforge.org/projects/rdoc/>
* <Documentation: http://rdoc.rubyforge.org/>
47b1910084592eb77a032bc7d8d1a84e?d=identicon&s=25 Joel VanderWerf (Guest)
on 2009-02-25 09:06
(Received via mailing list)
Eric Hodel wrote:
> * 9 Minor Enhancements
...
>   * Removed support for --accessor, use regular documentation or
>     the method directive instead.  See RDoc::Parser::Ruby

Ok, it's pretty minor and I can live without it, but .... "enhancement"?

Can the :method: directive emulate attr_reader, and really make the
output doc look the same as if attr_reader had been used instead of some
other class method? Is there a way to display "[R]", and group it with
other attrs?
Fbb4d027695dfdf76bf448b15d7e306a?d=identicon&s=25 matt neuburg (Guest)
on 2009-02-25 16:56
(Received via mailing list)
Eric Hodel <drbrain@segment7.net> wrote:

> rdoc version 2.4.0 has been released!

$ rdoc --version
rdoc 2.4.0
uh-oh! RDoc had a problem:
exit
run with --debug for full backtrace

$rdoc --debug --version
rdoc 2.4.0
exit
/usr/local/lib/ruby/1.8/optparse.rb:731:in `exit'
        /usr/local/lib/ruby/1.8/optparse.rb:731
        /usr/local/lib/ruby/1.8/optparse.rb:1260:in `call'
        /usr/local/lib/ruby/1.8/optparse.rb:1260:in `parse_in_order'
        /usr/local/lib/ruby/1.8/optparse.rb:1247:in `catch'
        /usr/local/lib/ruby/1.8/optparse.rb:1247:in `parse_in_order'
        /usr/local/lib/ruby/1.8/optparse.rb:1241:in `order!'
        /usr/local/lib/ruby/1.8/optparse.rb:1332:in `permute!'
        /usr/local/lib/ruby/1.8/optparse.rb:1353:in `parse!'

/usr/local/lib/ruby/gems/1.8/gems/rdoc-2.4.0/lib/rdoc/options.rb:410:in
`parse'

/usr/local/lib/ruby/gems/1.8/gems/rdoc-2.4.0/lib/rdoc/rdoc.rb:281:in
`document'
        /usr/local/lib/ruby/gems/1.8/gems/rdoc-2.4.0/bin/rdoc:15
        /usr/local/bin/rdoc:19:in `load'
        /usr/local/bin/rdoc:19
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2009-02-25 18:00
(Received via mailing list)
On Feb 25, 2009, at 07:54, matt neuburg wrote:
> Eric Hodel <drbrain@segment7.net> wrote:
>
>> rdoc version 2.4.0 has been released!
>
> $ rdoc --version
> rdoc 2.4.0
> uh-oh! RDoc had a problem:
> exit
> run with --debug for full backtrace

hahaha, awesome!

Fixed.
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2009-02-25 18:01
(Received via mailing list)
On Feb 25, 2009, at 00:04, Joel VanderWerf wrote:

> Eric Hodel wrote:
>> * 9 Minor Enhancements
> ...
>>  * Removed support for --accessor, use regular documentation or
>>    the method directive instead.  See RDoc::Parser::Ruby
>
> Ok, it's pretty minor and I can live without it, but ....
> "enhancement"?

I usually find deleting code is an enhancement :)

> Can the :method: directive emulate attr_reader, and really make the
> output doc look the same as if attr_reader had been used instead of
> some other class method? Is there a way to display "[R]", and group
> it with other attrs?

No.

I'm very strongly considering merging the attr-defined methods with
regular methods.  Present your counter-argument here.
47b1910084592eb77a032bc7d8d1a84e?d=identicon&s=25 Joel VanderWerf (Guest)
on 2009-02-25 18:33
(Received via mailing list)
Eric Hodel wrote:
> On Feb 25, 2009, at 00:04, Joel VanderWerf wrote:
>> Can the :method: directive emulate attr_reader, and really make the
>> output doc look the same as if attr_reader had been used instead of
>> some other class method? Is there a way to display "[R]", and group it
>> with other attrs?
>
> No.
>
> I'm very strongly considering merging the attr-defined methods with
> regular methods.  Present your counter-argument here.

Treating attrs the same as other methods does make sense in light of the
uniform access principle, but practically speaking it seems a bit
severe. Libraries like fxruby use the attribute section extensively, and
it is useful because the methods that appear there not only have more of
the attr-nature, but also are based on C++ public data members. It's a
helpful bridge back to the Fox world. Plus, it gives you a way to scan
the rdocs to see (i) what dials and switches can be adjusted on an
object ([W] and [RW]), and (ii) what constitutes the visible state of
the object ([R] and [RW]).

I guess :section: is a solution to this, but it will mean some work for
library maintainers, and :section: is not widely used. I have 221 gems
installed, and :section: appears only in rdoc, rubygems-update, and one
file in merb. I do use :section: extensively in my own rdocs. How long
will it take for all of the doc maintainers to respond to this change?
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2009-02-25 19:37
(Received via mailing list)
On Feb 24, 2009, at 22:03, Eric Hodel wrote:

>  * Moved HTML and XML generators to unmaintained
>    * No gem will be provided as it's too difficult to make them work
>    * Removed options --one-file, --style=, --inline-source, --
> promiscuous,
>      --op-name

One more thing, removing the HTML and XML generators allows RDoc to
build HTML output for the ruby 1.8 tree in under 200MB of memory.
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2009-02-25 19:41
(Received via mailing list)
On Feb 25, 2009, at 09:32, Joel VanderWerf wrote:
> Treating attrs the same as other methods does make sense in light of
> the uniform access principle, but practically speaking it seems a
> bit severe.

Yes, I was worried it would be too severe.  In terms of an API for
documentation generation it's easy to work provide uniform access.

> Libraries like fxruby use the attribute section extensively, and it
> is useful because the methods that appear there not only have more
> of the attr-nature, but also are based on C++ public data members.
> It's a helpful bridge back to the Fox world. Plus, it gives you a
> way to scan the rdocs to see (i) what dials and switches can be
> adjusted on an object ([W] and [RW]), and (ii) what constitutes the
> visible state of the object ([R] and [RW]).

Would adding a :attr: directive be an acceptable alternative?  This
would allow the documentation to be rendered as intended without a
command line flag.
47b1910084592eb77a032bc7d8d1a84e?d=identicon&s=25 Joel VanderWerf (Guest)
on 2009-02-25 20:19
(Received via mailing list)
Eric Hodel wrote:
> Would adding a :attr: directive be an acceptable alternative?  This
> would allow the documentation to be rendered as intended without a
> command line flag.

The effect of the :attr: directive would be that any invocation of the
specified class method was to be treated as an attr? Could a tag ("R"
etc.) be specified along with the class method? And would the new rdoc
still automatically recognize "attr_*" as attrs, without the explicit
directive? Sounds great to me, but it would be good to hear from more
library maintainers.
58479f76374a3ba3c69b9804163f39f4?d=identicon&s=25 Eric Hodel (Guest)
on 2009-02-25 20:35
(Received via mailing list)
On Feb 25, 2009, at 11:17, Joel VanderWerf wrote:
> Eric Hodel wrote:
>> Would adding a :attr: directive be an acceptable alternative?  This
>> would allow the documentation to be rendered as intended without a
>> command line flag.
>
> The effect of the :attr: directive would be that any invocation of
> the specified class method was to be treated as an attr? Could a tag
> ("R" etc.) be specified along with the class method?

Yes, I think:

# :attr_reader: method_name

will be clearer than having R/W/RW in case the attr isn't visible to
RDoc for some reason.

> And would the new rdoc still automatically recognize "attr_*" as
> attrs, without the explicit directive? Sounds great to me, but it
> would be good to hear from more library maintainers.

Yes.
This topic is locked and can not be replied to.