Rdoc 2.5 Released

Ruby
1

rdoc version 2.5 has been released!

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::Parser
    • 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::Parser::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::Parser::Ruby#parse_meta_attr.
    • Fix crossrefs on paths with ‘-’. Ruby Bug #883.
    • Fix ruby parser for alias with = 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 coding: 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.
2

On Apr 1, 2010, at 1:16, Eric H. [email protected] wrote:

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.

3

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

4

On Apr 1, 2010, at 12:08, Roger P. wrote:

You’ll need to:

gem install rdoc-data

then run:

rdoc-data

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.

5

Eric H. wrote:

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

6

On Apr 2, 2010, at 02:19, Marvin Gülker wrote:

#[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?

7

On Apr 2, 2010, at 14:24, Marvin Gülker wrote:

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.

8

Eric H. wrote:

On Apr 2, 2010, at 02:19, Marvin G�lker wrote:

#[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. :wink:

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