[ANN] rdoc 2.4.0 Released

[Eric Hodel]

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:arser::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/>

 

[Joel VanderWerf]

* 9 Minor Enhancements ...
* Removed support for --accessor, use regular documentation or
the method directive instead. See RDoc:arser::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?

 

[matt neuburg]

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

 

[Eric Hodel]

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

hahaha, awesome!

Fixed.

 

[Eric Hodel]

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.

 

[Joel VanderWerf]

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?

 

[Eric Hodel]

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

 

[Eric Hodel]

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.

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.

 

[Joel VanderWerf]

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.

 

[Eric Hodel]

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.