[ANN] rdoc 2.5 Released

[Eric Hodel]

rdoc version 2.5 has been released!

* RDoc Project Page http://rubyforge.org/projects/rdoc/
* RDoc Documentation http://rdoc.rubyforge.org/
* RDoc Bug Tracker =
http://rubyforge.org/tracker/?atid=3D2472&group_id=3D627&func=3Dbrowse

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.5 / 2010-03-31

*NOTE*:

You'll need to:

gem install rdoc-data

then run:

rdoc-data

to have ri data for core and stdlib like Array or Kernel or Date.

* 9 Major Enhancements
* Darkfish now has a "Home" button
* ri no longer displays the value of a constant. There's no easy way =
to
make them presentable. Use irb or ruby -e instead. Ruby Bug #549.
* New ri data format now uses Marshal and pre-builds caches
* No support for old ri data format, too hard to maintain
* To upgrade your core ri documentation, install the rdoc-data gem =
and run
rdoc-data
* RDoc now displays how well you've documented your library
* New recursive-descent parser for RDoc::Markup. See =
RDoc::Markup:arser
* Updated ruby_lex and ruby_token
* Removed threading support, RDoc is not thread-safe
* Removed many unsupported options to rdoc
* Future versions of RDoc will not support Ruby 1.8.6. Bugs filed for
1.8.6-only issues will be (largely) rejected.

* 17 Minor Enhancements
* Source Parsing
* RDoc now supports module aliasing via constant assignment.
* RDoc now tracks superclasses correctly. Fixes File < IO for core =
docs.
* RDoc now ignores methods inside methods.
* RDoc now ignores Marshal and other binray files.
* Removed "Skipping require of dynamic string" warning.
* C parser now handles Document-method better. Bug #27329.
* API enhancements for writing parsers like the Ruby parser, see
RDoc:arser::RubyTools
* ri
* Uses pager over less and more for Debian. Ruby Bug #1171.
* ri will use the RI_PAGER environment variable to find a pager.
* ri data generator now supports SIGINFO (^T)
* When rdoc is in debug mode, ^C now prints a backtrace
* RDoc::Markup::AttributeManager no longer uses global state.
* RDoc::RDoc no longer passes around options. Patch #27167.
* Darkfish won't generate a file if its template is missing. Patch =
#25857.
* Improved some wording for the RDoc main page. Patch #27264, #27268.
* Removed diagram generation support (to return in the future).
* Removed external support for RDoc::Task.

* 12 Bug Fixes
* The :attr: directives now use the name given to create an attribute. =
See
RDoc:arser::Ruby#parse_meta_attr.
* Fix crossrefs on paths with '-'. Ruby Bug #883.
* Fix ruby parser for alias with =3D in the name. Bug #27522.
* Images are no longer executable. Bug #27156.
* --op is no longer overridden by --ri. Bug #27054.
* :method: now works when at the end of a class. Bug #26910.
* Preserve elipsis from call-seq in Darkfish. Patch #26974.
* Emacs-style <tt>coding:</tt> is handled properly. Patch #27388.
* RDoc::RubyLex now parses UTF-8 identifiers. Bug #26946, #26947.
* Fixed namespace lookup rules. Bug #26161.
* Worked around bug in Selenium where they hide a .jar in a .txt file.
Filed Selenium bug #27789.
* Alias comments are no longer hidden. Reported by Adam Avilla.=

 

[Segment7]

rdoc version 2.5 has been released!

*NOTE*:

You'll need to:

gem install rdoc-data

then run:

rdoc-data

to have ri data for core and stdlib like Array or Kernel or Date.

One more thing, you'll need to rebuild ri data for gems too:

gem rdoc --all --overwrite --no-rdoc

If you want that glorious Home link in your 'gem server' output remove
--no-rdoc.

 

[Roger Pack]

You'll need to:

gem install rdoc-data

then run:

rdoc-data

Thanks for the update. Appears to parse the core stuffs well now.
-rp

 

[Eric Hodel]

=20
Thanks for the update. Appears to parse the core stuffs well now.

I made sure to make rdoc parsing be warning-free for ruby (and most =
other gems).

I ran rdoc 2.5 against all the released gems using gauntlet and found =
under five that RDoc couldn't handle. I think one had .rb files that =
didn't contain ruby and another two had hundred-thousand-character long =
line that was a single constant. I think rdoc would succeed on those =
really-really-really-long-constants when I didn't get impatient.=

 

[Marvin Gülker]

rdoc version 2.5 has been released!

Why don't you allow headings in method documentations any more? I've
become used to document my methods like this:

-----------------------------------------------
#Method description
#===Parameters
#[par1] This and that...
#[par2] foo bar
#===Return value
#This will be returned...
#===Example
# #Some example code
#===Remarks
#This has to be mentioned, too.
def my_awesome_method(par1, par2)
#Code...
end
-----------------------------------------------

When I try to document this, all the equal signs show up in the output.
Btw. this is the same for the C parser.

Marvin

 

[Eric Hodel]

=20
Why don't you allow headings in method documentations any more? I've=20=

become used to document my methods like this:
=20
-----------------------------------------------
#Method description
#=3D=3D=3DParameters
#[par1] This and that...
#[par2] foo bar
#=3D=3D=3DReturn value
#This will be returned...
#=3D=3D=3DExample
# #Some example code
#=3D=3D=3DRemarks
#This has to be mentioned, too.
def my_awesome_method(par1, par2)
#Code...
end

This is a bug. Do you have a released gem I can look at to be sure I've =
fixed it?=

 

[Marvin Gülker]

#[par2] foo bar

When I try to document this, all the equal signs show up in the output.
Btw. this is the same for the C parser.

This is a bug. Do you have a released gem I can look at to be sure I've
fixed it?

I'm the maintainer of the gems au3 and xdo, but when I released them I
wasn't as detailed as I am now. ;-)

However, I'm working on a third gem, don't assume this works, but the
documentation is already there (with details!). Just look at the
Imitator::X::XWindow class (btw. the XWindow.search class method also
illustrates the multiline :call-seq: issue). Just run "rake rdoc".
I've attached my work.

Marvin

Attachments:
http://www.ruby-forum.com/attachment/4638/imitator_x.tar.bz2

 

[Eric Hodel]

=20
I'm the maintainer of the gems au3 and xdo, but when I released them I=20=

wasn't as detailed as I am now. ;-)
=20
However, I'm working on a third gem, don't assume this works, but the=20=

documentation is already there (with details!). Just look at the=20
Imitator::X::XWindow class (btw. the XWindow.search class method also=20=

illustrates the multiline :call-seq: issue). Just run "rake rdoc".
I've attached my work.

I've confirmed this is fixed this in trunk. I have one other bug report =
from ruby core to fix then I should be able to release.