ruby / rdoc

RDoc produces HTML and online documentation for Ruby projects.

RDoc - Ruby Documentation System¶ ↑

home

github.com/ruby/rdoc

rdoc

ruby.github.io/rdoc

bugs

github.com/ruby/rdoc/issues

code quality

codeclimate.com/github/ruby/rdoc

Description¶ ↑

RDoc produces HTML and command-line documentation for Ruby projects. RDoc includes the rdoc and ri tools for generating and displaying documentation from the command-line.

Generating Documentation¶ ↑

Once installed, you can create documentation using the rdoc command

$ rdoc [options] [names...]

For an up-to-date option summary, type

$ rdoc --help

A typical use might be to generate documentation for a package of Ruby source (such as RDoc itself).

$ rdoc

This command generates documentation for all the Ruby and C source files in and below the current directory. These will be stored in a documentation tree starting in the subdirectory doc.

You can make this slightly more useful for your readers by having the index page contain the documentation for the primary file. In our case, we could type

% rdoc --main README.rdoc

You’ll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.

RDoc uses file extensions to determine how to process each file. File names ending .rb and .rbw are assumed to be Ruby source. Files ending .c are parsed as C files. All other files are assumed to contain just Markup-style markup (with or without leading ‘#’ comment markers). If directory names are passed to RDoc, they are scanned recursively for C and Ruby source files only.

To generate documentation using rake see RDoc::Task.

To generate documentation programmatically:

gem 'rdoc'
require 'rdoc/rdoc'

options = RDoc::Options.new
# see RDoc::Options

rdoc = RDoc::RDoc.new
rdoc.document options
# see RDoc::RDoc

Writing Documentation¶ ↑

To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:

##
# This class represents an arbitrary shape by a series of points.

class Shape

  ##
  # Creates a new shape described by a +polyline+.
  #
  # If the +polyline+ does not end at the same point it started at the
  # first pointed is copied and placed at the end of the line.
  #
  # An ArgumentError is raised if the line crosses itself, but shapes may
  # be concave.

  def initialize polyline
    # ...
  end

end

The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported. You can set the default comment format for your entire project by creating a .rdoc_options file. See RDoc::Options@Saved+Options for instructions on creating one. You can also set the comment format for a single file through the :markup: directive, but this is only recommended if you wish to switch markup formats. See RDoc::Markup@Other+directives.

Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.

See RDoc::Parser::C for documenting C extensions with RDoc.

To determine how well your project is documented run rdoc -C lib to get a documentation coverage report. rdoc -C1 lib includes parameter names in the documentation coverage report.

Bugs¶ ↑

See CONTRIBUTING@Bugs for information on filing a bug report. It’s OK to file a bug report for anything you’re having a problem with. If you can’t figure out how to make RDoc produce the output you like that is probably a documentation bug.

License¶ ↑

RDoc is Copyright © 2001-2003 Dave Thomas, The Pragmatic Programmers. Portions © 2007-2011 Eric Hodel. Portions copyright others, see individual files and LEGAL.rdoc for details.

RDoc is free software, and may be redistributed under the terms specified in LICENSE.rdoc.

Warranty¶ ↑

This software is provided “as is” and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.

rdoc's Issues

error installing gem

when i try to install the gem i get this error:

Successfully installed rdoc-3.1
1 gem installed
Installing ri documentation for rdoc-3.1...
Installing RDoc documentation for rdoc-3.1...
ERROR: While executing gem ... (Encoding::UndefinedConversionError)
U+2019 from UTF-8 to IBM437

also doing gem install rdoc-data gives:

Successfully installed rdoc-data-2.5.3
1 gem installed
Installing ri documentation for rdoc-data-2.5.3...
Installing RDoc documentation for rdoc-data-2.5.3...
ERROR: While executing gem ... (Encoding::UndefinedConversionError)
U+2013 from UTF-8 to IBM437

i'm running ruby 1.9.2p136 (2010-12-25) [i386-mingw32]

i also had this problem trying to install the rdoc 3.0 gem, but was too lazy to report it (sorry). let me know if you need any more information (and how to get said information). thanks.

hex

undefined method `group_by' for []:Array (RDoc::Error)

When Rdoc-ing a very simple file I get an RDoc error:

C:\tmp>type example.rb
class SomethingHappenedError < StandardError; end

C:\tmp>gem list rdoc

*** LOCAL GEMS ***

rdoc (3.6.1, 3.5.3, 2.5.8)

C:\tmp>ruby -v
ruby 1.9.2p180 (2011-02-18) [i386-mingw32]

C:\tmp>rdoc
Parsing sources...
100% [ 1/ 1] example.rb

Generating Darkfish format into C:/Users/s.kaemper/Downloads/tmp/doc...
uh-oh! RDoc had a problem:
error generating SomethingHappenedError.html: Error while evaluating c:/Fe-Al2O3/Lib/ruby/gems/1.9.1/gems/rdoc-3.6.1/lib/rdoc/generator/templa
te/darkfish/classpage.rhtml: undefined method `group_by' for []:Array (RDoc::Error)

run with --debug for full backtrace

The system is a Windows 7 machine running ruby 1.9.2p180 (2011-02-18) [i386-mingw32](the one click installer).
This also happens when using IronRuby on the same box.

nested list items broken

* Quick and easy inlining of your C or C++ code embedded in your ruby script.
* Extendable to work with other languages.
* Automatic conversion between ruby and C basic types
  * char, unsigned, unsigned int, char *, int, long, unsigned long
* inline_c_raw exists for when the automatic conversion isn't sufficient.
* Only recompiles if the inlined code has changed.
* Pretends to be secure.
* Only requires standard ruby libraries, nothing extra to download.

Indented bullet doesn't become a nested list item

Link to Plurals of class names

As requested, I'm opening an issue based upon this ruby forum thread:

http://www.ruby-forum.com/topic/931304#976952

This is kinda going to be a slippery slope I'm afraid. I guess you could do a simple "remove the trailing s" and look. But a general way to link to the Class's page would be nice too so that I can do "list of children[class_link:Child]" (perhaps) and RDoc would fill in the proper link to the page for Child.

Good luck!
pedz

:stopdoc: directive produces Object reference

The :stopdoc: directive produces a reference to Object as a class/module when used like this:

# :stopdoc:
class Example
  def method_name
  end
end

I generated the RDoc with:

rdoc example.rb

Incidentally, no reference to Object is generated unless the method is defined. This is ok:

# :stopdoc:
class Example
end

Using RDoc 3.8.

:section: command not generating sections

RDoc::Context::Section indicates that you can use :section: to group methods together. However, there is no indication that this produces any output whatsoever.

does not compile with ruby 1.8.7 p302

I try to compile rdoc 3.6 for ruby 1.8.7 p302 on FreeBSD, but it fails.
Is rdoc 3.6 expected to only work with ruby 1.9 or sould it work with ruby 1.8, too?

/usr/bin/env  /usr/local/bin/gem18 install -l --no-update-sources --no-ri --install-dir /usr/local/lib/ruby/gems/1.8 /tmp/distfiles/rubygem/rdoc-3.6.gem -- --build-args 
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has invalid interval
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:153: warning: regexp has `}' without escape


RDoc failure in lib/rdoc/markup.rb at or around line 532 column 0

Before reporting this, could you check that the file
you're documenting compiles cleanly--RDoc is not a
full Ruby parser, and gets confused easily if fed
invalid programs.

The internal error was:

ERROR:  While generating documentation for rdoc-3.6
... MESSAGE:   invalid regular expression: /##
# RDoc::Markup parses plain text documents and attempts to decompose them into
# their constituent parts.  Some of these parts are high-level: paragraphs,
# chunks of verbatim text, list entries and the like.  Other parts happen at
# the character level: a piece of bold text, a word in code font.  This markup
# is similar in spirit to that used on WikiWiki webs, where folks create web
# pages using a simple set of formatting rules.
#
# RDoc::Markup itself does no output formatting: this is left to a different
# set of classes.
#
# RDoc::Markup is extendable at runtime: you can add \new markup elements to
# be recognised in the documents that RDoc::Markup parses.
#
# RDoc::Markup is intended to be the basis for a family of tools which share
# the common requirement that simple, plain-text should be rendered in a
# variety of different output formats and media.  It is envisaged that
# RDoc::Markup could be the basis for formatting RDoc style comment blocks,
# Wiki entries, and o
... RDOC args: --op /usr/local/lib/ruby/gems/1.8/doc/rdoc-3.6/rdoc --main README.txt lib History.txt LICENSE.txt Manifest.txt README.txt RI.txt Rakefile --title rdoc-3.6 Documentation --quiet
Successfully installed rdoc-3.6
1 gem installed
Installing RDoc documentation for rdoc-3.6...
*** Error code 1

Indented example not rendering lines

Example text (i.e. indented text) is not rendering correctly when long '=============' lines are used. See:

https://github.com/TwP/turn/blob/master/README.rdoc

Bug? Or am I doing something wrong?

Markdown Parser that generates a usable parse tree, not HTML

I have wanted this for a while, but writing it is time consuming.

Windows RDoc encoding issue

Hello,

Running command:
C:\Users\vita.pik\rubies\Ruby-193-dev\lib\ruby\gems\1.9.1\gems\bundler-1.0.9>rdoc --op C:/Users/vita/.pik/rubies/Ruby-193-dev/lib/ruby/gems/1.9.1/doc/bundler-1.0.9/rdoc lib --title="bundler-1.0.9 Documentation" -v --debug 2> \temp\rdoc.log

to install Bundler documentation produces following codepage conversion error: http://pastie.org/1506876

C:\>rdoc --version
rdoc 3.1

C:\>ruby --version
ruby 1.9.3dev (2011-01-28) [i386-mingw32]

C:\>chcp
Aktivní znaková stránka: 852

Changing codepage to 65001 (utf-8) does not produce the error. However it is mystery to me why should documentation generation depend on current console codepage.

rdoc --main shouldn't create a separate index.html

The generated page with the sidebar is much more preferable to the index page we're creating. Nuke the index and just use the page specified in main (even if generated twice... who cares).

TopLevel#absolute_name not very absolute?

Using Ruby 1.9.2, TopLevel#absolute_name returns the same a #relative_name.

So how to get full pathname of a toplevel file?

=begin rdoc...=end block style problem when there's code before them

This is similar to https://github.com/rdoc/rdoc/issues/22 but I can't figure it out to be working in my case.

Using ruby 1.9.2p180 and rdoc 3.6.1. I see that https://github.com/rdoc/rdoc/issues/22 and https://github.com/rdoc/rdoc/pull/25 both were closed on April 13th and that 3.6.1 was last modified on May 16th ( https://github.com/rdoc/rdoc/commits/v3.6.1/ ), I also see the fix from the pull ( https://github.com/sgharms/rdoc/commit/e1451cd9396fb8b9692fd804066b6d66124de93f ) in my local version I've installed via gem.

Test case 1: rdoc for module is not generated

require 'something'
=begin rdoc
findmeindoc
=end
module Foo
    class Bar
    end
end

yeilds to

$ rm -Rf doc && rdoc -v test2.rb
Parsing sources...
100% [ 1/ 1]  test2.rb
  class Bar (undocumented)


Generating Darkfish format into ...

I.e. the module is ignored completely.

Removing the require line or moving it below the rdoc works:

=begin rdoc
findmeindoc
=end
require 'something'
module Foo
    class Bar
    end
end

yields to

$ rm -Rf doc && rdoc -v test3.rb
Parsing sources...
100% [ 1/ 1]  test3.rb
  class Foo::Bar (undocumented)
  module Foo (undocumented)

Similar, when I've two modules in a file, only the first one gets documented when using =begin and =end:

=begin rdoc
findmeindoc
=end
module Foo
end

=begin rdoc
findme2indoc
=end
module Frob
end

yields to

$ rm -Rf doc && rdoc -v test8.rb
Parsing sources...
100% [ 1/ 1]  test8.rb
  module Foo

Commandline option -f doesn't override RDOCOPT's value

Hi there,

RDoc's help states this:

    Options can be specified via the RDOCOPT environment variable, which
    functions similar to the RUBYOPT environment variable for ruby.

      $ export RDOCOPT="--show-hash"

    will make rdoc show hashes in method links by default.  Command-line options
    always will override those in RDOCOPT.

However, this is not true for the -f commandline option as can be seen in this gist (the interesting part is the last execution of RDoc where I set RDOCOPT to -f hanna and request darkfish via rdoc -f darkfish.

Instead of RDoc using darkfish instead of RDOCOPT's hanna, RDoc states this:

    invalid options: -f generator already set to hanna
    (invalid options are ignored)

and continues to use the hanna generator.

ruby -v: ruby 1.9.2p290 (2011-07-09 revision 32553) [x86_64-linux]
rdoc --version: rdoc 3.9.2
OS: Arch Linux

Valete,
Marvin

PS: Shouldn't the --formatter option be named --generator? darkfish, hanna, and all those are generators rather than formatters.

Parser confused by "alias * ..."

The following was caused by alias * multiply in eymiha_math3 gem:

$ gem install eymiha_math3
[...]
Installing ri documentation for eymiha_math3-1.0.2...

RDoc::Parser::Ruby failure around line 197 of
lib/eymiha/math3/point3.rb

Before reporting this, could you check that the file you're documenting
compiles cleanly--RDoc is not a full Ruby parser, and gets confused easily if
fed invalid programs.

The internal error was:

    (RDoc::Error) Name or symbol expected (got #<RDoc::RubyToken::TkSTAR:0x00000102afce88>)

ERROR:  While generating documentation for eymiha_math3-1.0.2
... MESSAGE:   Name or symbol expected (got #<RDoc::RubyToken::TkSTAR:0x00000102afce88>)
... RDOC args: --ri --op /Users/artm/.rvm/gems/ruby-1.9.2-p180@brahmix/doc/eymiha_math3-1.0.2/ri --all lib --title eymiha_math3-1.0.2 Documentation --quiet

attribute manager is not passed to formatter

Hi,

In the documentation (3.6.1) there's an example that shows how to extend RDoc::Markup parser (i.e. ToHtml):

"You can extend the RDoc::Markup parser to recognise new markup sequences, and to add special processing for text that matches a regular expression. Here we make WikiWords significant to the parser, and also make the sequences {word} and text… signify strike-through text. When then subclass the HTML output class to deal with these:"

require 'rdoc/markup'
require 'rdoc/markup/to_html'

class WikiHtml < RDoc::Markup::ToHtml
  def handle_special_WIKIWORD(special)
    "<font color=red>" + special.text + "</font>"
  end
end

m = RDoc::Markup.new
m.add_word_pair("{", "}", :STRIKE)
m.add_html("no", :STRIKE)

m.add_special(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)

wh = WikiHtml.new
wh.add_tag(:STRIKE, "<strike>", "</strike>")

puts "<body>#{wh.convert ARGF.read}</body>"

As far as I can tell the RDoc::Markup instance or its attribute manager isn't passed to the formatter anywhere, so that won't work. The formatter seems to create its own attribute manager with some default specials, but there seems to be no way to access it to add own specials to it. Thus RDoc::Markup's add_special method won't do anything.

Before it used to work with m.convert(string, wh) but in the newer versions convert() just creates an instance of RDoc::Markup::Document, parses it and passes to formatter with no reference to self so the specials added with m.add_special() won't get passed there.

Am I missing something?

Rdoc includes the magic #encoding comment in output, it shouldn't

Consider:

#encoding: utf-8
#   

class Blah
  TRIGGER = "amō amāre amāvī amatum"
end 

By using that language of IVLUS CAESAR, Ruby will complain if the #encoding is not there when we check syntax:

$ruby -c blah.rb
blah.rb:2: invalid multibyte char (US-ASCII)
blah.rb:2: invalid multibyte char (US-ASCII)

But of course...

$ ruby -KU -c ./blah.rb 
Syntax OK

OK, so magic comments gotta be there. But the comment is carried into the RDoc output. If you have multiple mixed in files where the encoding is specified, you get the eyesore of 6-7 of these encoding lines being at the top of your documentation.

Here is a suitable bit of code that triggers the error:

    #encoding: utf-8
    #

    class Blah
      TRIGGER = "amō amāre amāvī amatum"
    end

Generator Names

Currently RDoc gets the name of a custom generator from the base of Class#name. But if one wants to name the class differently then there's no way to change it. The work around is to override the name class method, but that's a hack. It would be nice if the name could be overridden with a separate method, e.g.

# File lib/rdoc/rdoc.rb, line 84
def self.add_generator(klass)
  if klass.respond_to?(:generator_name)
    name = klass.generator_name.to_s.downcase
  else
    name = klass.name.sub(/^RDoc::Generator::/, '').downcase
  end
  GENERATORS[name] = klass
end

Also, I notice in the rdoc output that there it some other place in the code where it is getting the name from the name class method --that would need to be adjusted too.

Btw, as things currently stand the example given in the docs:

class My::Awesome::Generator
  RDoc::RDoc.add_generator self
end

would appear with a format name of generator.

Document-attr: name with C parser did not work

hello i have two functions (getter and setter) but i whould like that rdoc dont show it as methods, i should show it as a Attribute with rw, is it possible?

dependency discrepancy

It seems that isolate is directly required in order for any of the rake tasks to carry on with their meaningful business. Such as rake test.

Also, without the git and minitest plugins, rake tasks will continue. However, if one desires to test the full suite of rdoc they are required to install hoe-git and hoe-seattlerb. These could be made actual dependencies, or my suggestion is to specify which gem is actually required in the "warning: couldn't activate the plugin, skipping". Which currently leaves one to take a guess or do some searching for the right gems.

RDoc generation fails on every gem install

This may be related to rdoc not support RUBYOPT="-Ku"; however, I tried the two solutions mentioned, and neither worked. That said, the similiar solution of adding the magic encoding comment # encoding: ascii to ruby_lex.rb did solve the problem.

This happens on every gem install that I have tried.

Error:

$ gem install hoe-git
Successfully installed hoe-git-1.4.0
1 gem installed
/Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require': /Users/travis/.rvm/gems/ruby-1.9.3-preview1@rails3-dev/gems/rdoc-3.9.2/lib/rdoc/ruby_lex.rb:833: invalid multibyte escape: /[\w\x80-\xFF]/ (SyntaxError)
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
    from /Users/travis/.rvm/gems/ruby-1.9.3-preview1@rails3-dev/gems/rdoc-3.9.2/lib/rdoc/parser/ruby.rb:12:in `<top (required)>'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
    from /Users/travis/.rvm/gems/ruby-1.9.3-preview1@rails3-dev/gems/rdoc-3.9.2/lib/rdoc/rdoc.rb:8:in `<top (required)>'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/doc_manager.rb:42:in `load_rdoc'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/doc_manager.rb:214:in `setup_rdoc'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/doc_manager.rb:115:in `generate_ri'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/commands/install_command.rb:148:in `block in execute'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/commands/install_command.rb:147:in `each'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/commands/install_command.rb:147:in `execute'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/command.rb:278:in `invoke'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/command_manager.rb:147:in `process_args'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/command_manager.rb:117:in `run'
    from /Users/travis/.rvm/rubies/ruby-1.9.3-preview1/lib/ruby/site_ruby/1.9.1/rubygems/gem_runner.rb:65:in `run'

Environment

• OS: OS X Lion
• Ruby 1.9.3-preview1
• Using RUBYOPT=-Ku
• RDoc 3.9.2
• RVM 1.6.32

make docs fails on trunk

make docs fails on trunk:

[...]
Generating RDoc documentation
Parsing sources...
uh-oh! RDoc had a problem:
stack level too deep
lib/rdoc/context.rb:967

It seems to be related to methods_matching in lib/rdoc/context.rb, being called a lot on:

#<RDoc::NormalModule:0x810fc1a8 module CMath ...>

CMath has lib/cmath.rb for parent, and each_ancestor do |parent| yields CMath (itself), which likely cause the infinite loop.

Line with "#--" not working according to documentation.

So far we have been using the RDoc version included in the Standard Library for Ruby version 1.8.7. That is RDoc version 1.0.1.

Our coding style specifies method comments formatted like this:

#---------------------------------------------------------------------
#++
# <method description>
#---------------------------------------------------------------------
def foobar()
  ...
end

We have chosen this style as the "#---..." lines nicely highlight a comment for someone looking at the source code. This is obviously a matter of taste.

The line starting with "#--" and all following lines up to and including the line starting with "#++" are discarded by RDoc while generating HTML. In this case there are no lines in between start and stop.

Well, we have now been trying RDoc version 3.3, and a line starting with "#--" no longer turns off RDoc generation. That is, unless the line contains only "#--" followed by a newline. If "#--" is followed by any other character, it does not work.

The RDoc 3.3 documentation says:

"RDoc stops processing comments if it finds a comment line starting with -- right after the # character (otherwise, it will be treated as a rule if it has three dashes or more). This can be used to separate external from internal comments, or to stop a comment being associated with a method, class, or module. Commenting can be turned back on with a line that starts with ++."

I have managed to get it to work by modifying the regular expressions in method "remove_private_comments" in file "lib/rdoc/parser/ruby.rb":

##
# Removes private comments from +comment+

def remove_private_comments(comment)
  comment.gsub!(/^#--.*\n(.*\n)*?^#\+\+.*\n?/, '')
  comment.sub!(/^#--.*/m, '')
end 

I believe this now works as documented. You may be able to improve on my regular expressions as I am far from an expert.

Best regards,

Claus Folke Brobak
JN Data, Denmark

3(---) or more dashes in comments are not being converted to a horizontal rule

Per the documentation if a line begins with 3 or more dashes it should be converted to a horizontal rule. I believe this is a regression that was introduced when this issue was fixed. https://github.com/rdoc/rdoc/issues/closed#issue/7

Cannot effectively link to a method in the same class

Given code like:

class FooController < ApplicationController

  # The intention here is to detect any problems with the requested URL before
  # it is loaded in an iframe (see FooController#preview).
  def preview_init
    # work... 
  end

  # This fetches a remote page and prepares it for viewing in an iframe.
  def preview
    # work...
  end
end

The outputting documentation for default_init will indeed link to FooController#preview, but clicking it merely expands the source for preview_init.

It seems that the click handler needs to check to see if the event.target is actually a link, in which case it should not do anything, and allow the default action to proceed.

Distance recommendations for ri

Could work similar to rubygems' levenshtein matcher, e.g.:

 $ ri Hash.deltee
 WHY HELLO THERE PILGRIM: DID YOU MEAN Hash#delete ?

hanna-nouveau: Method names not in alphabetical order

The hanna-nouveau project of RDoc seems to have no issue tracker, so I'll report it here.

The method names inside each class's documentation are in the order in which they're defined in the files, but I really think they should be in alphabetical order, because I often find myself skimming through a method list when searching for a method that "could be named like this, or like that..." where my browser's search function doesn't do the trick.

Here's a patch to accomplish this:

--- lib/hanna-nouveau.rb.old    2011-04-19 21:09:24.292692362 +0200
+++ lib/hanna-nouveau.rb    2011-04-19 21:09:30.296025495 +0200
@@ -173,9 +173,9 @@
             # FIXME linkify
             :classlist => '<ol>' + klass.classes_and_modules.inject('') { |x,y| x << '<li>' + y.name + '</li>' } + '</ol>',
             :constants => klass.constants,
-          :aliases   => klass.method_list.select { |x| x.is_alias_for },
-          :attributes => klass.attributes,
-          :method_list => klass.method_list.select { |x| !x.is_alias_for }
+          :aliases   => klass.method_list.select{ |x| x.is_alias_for }.sort,
+          :attributes => klass.attributes.sort,
+          :method_list => klass.method_list.select{ |x| !x.is_alias_for }.sort
           }
         } 

Thanks for consideration.
Marvin

Is there a way to portably create a 'link:' ?

I often want to link to other files (licenses, help docs, etc) in my RDoc. In RDoc 1.0 such links can be made using something like:

{file}[link:files/file_name_ext.html]

But as pointed out in an issue regarding YARD and rubydoc.info, this syntax assumes the location of the file. Obviously the links break between RDoc/YARD, but I found they also break between RDoc 1.0 and RDoc 3.8. It also breaks on GitHub... rendered .rdoc files have links that don't link to the intended files.

Maybe nothing can be done for everywhere, but is there a way to write portable links between RDoc 1.0 and RDoc 3.8? I'd like these links to work when people install the RDoc via Rubygems and I don't think I can assume RDoc 3.8 has been installed. If there is one, I plan on submitting a pull request to the GitHub markup library so that links can work on GitHub (it may involve a little gsub to reference the file in the repo but who knows they may go for it).

This gist illustrates the issue: https://gist.github.com/1097310 Generate with:

rdoc --main README.rdoc README.rdoc file.txt

When you use RDoc 1.0 you get a working link and a file like 'doc/files/file_txt.html'. When you use RDoc 3.8 you get a broken link and a file like 'doc/file_txt.html'.

=begin rdoc...=end bloc style comments seem to be broken

In the distant, dusty era of Ruby 1.8x, I wrote documentation in Ruby and used the =begin rdoc...=end bloc. I recently dusted off some code of this era and, having 1.9x-converted the code, was wurprised to see that my RDod information was ignored or not used.

Further the rdoc -C coverage metric did not consider the documentation I wrote in these blocs.

In an attempt to see if this had been fixed in intervening times, I grabbed the latest rdoc from github and tried compiling the docs using it. Nevertheless, I find, that using the =begin rdoc...=end fails both in RVM-packaged rubies as well as using the latest rdoc binary.

The comment anchored documentation (#) work as predicted.

If the bloc-style annotation is no longer to be used, can we get that put in ink somewhere? Otherwise, I think this is a bug. I have attempted to document my observations with simple test cases at the rdoc_wtf project.

I may attempt to fork this and fix it, but I would really like to have a developer on the project confirm that what i'm seeing is not a one-off.

Thanks,

Steven

Encoding::ConverterNotFoundError

I am getting this error message:

error generating /Users/pedzan/Source/Rails/raptor/doc/app/app/controllers/application_controller_rb.html: code converter not found (UTF8-MAC to US-ASCII) (Encoding::ConverterNotFoundError)

I am using:

• ruby 1.9.1p378 (2010-01-10 revision 26273) [i386-darwin10.7.1]
• rdoc 3.5.3
• rdoc-data 2.5.3

I realize that this may be an incomplete report. I'm happy to it but I'm kinda lost as to what is happening. I posted this on the Ruby list on 4/11 but got no replies.

If it helps, the contents of the mentioned file (which appears to not have been completed) is:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />

  <title>File: 

I have this:

# -*- coding: utf-8 -*-

at the top of almost all of my files.

ri -a option to display docs for all methods associated with class

It would be great if you could list the documentation for all methods associated with a class.

So if I'd do ri -a Array I'd get the normal Array documentation followed by the actual documentation of all the Array methods.

FastRI does this, and it's great feature when you need to browse the docs for a particular class or gem. You can then use the search feature of your pager to search this list for solutions.

Parser::C: in file work only with c and y, need cpp

could you please add the the in file function for multiple funcs please work on cpp files? because i write my gem code in cpp the infile parser does not work

Parser::C should differentiate between single/module functions from instance methods

maybe inside #find_override_comment() or the callers results could detect a '.' or '#' for singleton or instance, respectively.

example of where this can be found:
Public Class or Public instance of 'Zlib::Inflate.inflate'

it is showing the same comment for both, picked up from 'Document-method: Zlib::Inflate.inflate', not using ' Document-method: Zlib::Inflate#inflate' at all.

Take care,
vb

Allow Aggregating Data From Multiple Sources

I tried looking through RDoc's docs and source, but didn't really see a good way to do this. My goal was to generate docs and then pull in extra data from another source to provide extra content.

For instance the RubySpec specs are very well formatted, it would be awesome to scan then and say annotate the RDoc for Date#+ with the it or should clauses in date's add_spec.rb. The final documentation for Date#+ would then read:

Return a new Date object that is +n+ days later than the
current one.

+n+ may be a negative value, in which case the new Date
is earlier than the current one; however, #-() might be
more intuitive.

If +n+ is not a Numeric, a TypeError will be thrown.  In
particular, two Dates cannot be added to each other.

Spec:
* should add a number of days to a Date
* should add a negative number of days to a Date
* should raise an error on non numeric parameters

Anyways, I thought I would open this issue for comments. If someone wanted to point me in the right direction, I'd like to at least try it.

Ancient documentation

Exists at http://rdoc.sourceforge.net/

This site should be taken down or updated to point to the current sites.

ordered list formatting incorrect

For ordered lists, recent versions of rdoc

• produce a bullet (as in unordered lists) in addition to the number,
• place the enumeration marks off into the left margin.

ri cache file remembers methods that have been removed on subsequent runs

After running rdoc --ri on a file, renaming or removing a method in that file and running rdoc --ri on that file again, the cache.ri file retains information on the old method name, which is in effect no longer available.

Clicking on a file in the file index could display full file contents

The current view of a file (as opposed to a class or module) is not that useful. It would be nice if you are looking at files to just have the full source. With or without syntax highlighting. i.e. just serve the file.

The rationale is: when I am browsing rdoc, i often have a question that i am trying to answer. if the rdoc itself is not answering the question, the full source might. Of course the full source is available in other forms, but not having to switch applications or websites is helpful.

RDoc and Hoe don't place nice together under ruby-1.9.2-rc2

sgharms@stharms-mac:~/gitcheckouts/rdoc$ rake -T
(in /Users/sgharms/gitcheckouts/rdoc)
rake aborted!
no such file to load -- hoe
/Users/sgharms/gitcheckouts/rdoc/Rakefile:1:in `require'
(See full trace by running task with --trace)
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem list

*** LOCAL GEMS ***

rake (0.8.7)
rdoc (3.5.3, 2.5.11)
rubygems-update (1.6.2)
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem install hoe
ERROR:  Error installing hoe:
        hoe requires RubyGems version >= 1.4. Try 'gem update --system' to update RubyGems itself.
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem update --system
Updating RubyGems
Updating rubygems-update
Successfully installed rubygems-update-1.6.2
Updating RubyGems to 1.6.2
Installing RubyGems 1.6.2
/Users/sgharms/.rvm/gems/ruby-1.9.2-rc2@rdoc/gems/rubygems-update-1.6.2/lib/rubygems/gem_runner.rb:84:in `': undefined method `load_plugins' for Gem:Module (NoMethodError)
        from setup.rb:25:in `require'
        from setup.rb:25:in `'
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem list

*** LOCAL GEMS ***

rake (0.8.7)
rdoc (3.5.3, 2.5.11)
rubygems-update (1.6.2)
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem install hoe
ERROR:  Error installing hoe:
        hoe requires RubyGems version >= 1.4. Try 'gem update --system' to update RubyGems itself.

---

If I down-revision, things work fine.....

---

sgharms@stharms-mac:~/gitcheckouts/rdoc$ rvm use ruby-1.9.1-p378

info: Using ruby 1.9.1 p378
sgharms@stharms-mac:~/gitcheckouts/rdoc$ rvm gemset create rdoc

info: Gemset 'rdoc' created.
sgharms@stharms-mac:~/gitcheckouts/rdoc$ rvm use ruby-1.9.1-p378@rdoc

info: Using ruby 1.9.1 p378 with gemset rdoc
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem list

*** LOCAL GEMS ***

rake (0.8.7)
rdoc (3.5.3, 2.5.9)
rubygems-update (1.6.2, 1.3.7)
sgharms@stharms-mac:~/gitcheckouts/rdoc$ rake -T
(in /Users/sgharms/gitcheckouts/rdoc)
rake aborted!
no such file to load -- hoe
/Users/sgharms/gitcheckouts/rdoc/Rakefile:1:in `'
(See full trace by running task with --trace)
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem install hoe
Fetching: hoe-2.9.1.gem (100%)
Successfully installed hoe-2.9.1
1 gem installed
Installing ri documentation for hoe-2.9.1...
Installing RDoc documentation for hoe-2.9.1...
sgharms@stharms-mac:~/gitcheckouts/rdoc$ rake -T
(in /Users/sgharms/gitcheckouts/rdoc)
rake aborted!
undefined method `isolate_dir=' for #
/Users/sgharms/gitcheckouts/rdoc/Rakefile:23:in `block in '
(See full trace by running task with --trace)
sgharms@stharms-mac:~/gitcheckouts/rdoc$ gem install isolate && rake -T
Fetching: isolate-3.0.0.gem (100%)
Successfully installed isolate-3.0.0
1 gem installed
Installing ri documentation for isolate-3.0.0...
Installing RDoc documentation for isolate-3.0.0...
(in /Users/sgharms/gitcheckouts/rdoc)
rake announce              # publish   # Announce your release.
rake audit                 # test      # Run ZenTest against the package.
rake check_extra_deps      # deps      # Install missing dependencies.
rake check_manifest        # debug     # Verify the manifest.

snip

Question:

Does some language need to be provided against using recent 1.9.2 versions against RDoc be given?

"unable to convert warnings" when installing builder gem

I get the following warnings when installing the builder gem using the latest RDoc and RubyGems on 1.9.2.

 ☣ ruby --version
ruby 1.9.2p180 (2011-02-18 revision 30909) [x86_64-darwin10.6.0]
 ☣ gem --version
1.8.5
 ☣ rdoc --version
rdoc 3.6.1
 ☣ echo $LANG              
en_US.UTF-8
 ☣ gem install builder
Successfully installed builder-3.0.0
1 gem installed
Installing ri documentation for builder-3.0.0...
unable to convert "\xF1" from ASCII-8BIT to UTF-8 for README, skipping
unable to convert "\xF1" from ASCII-8BIT to UTF-8 for README.rdoc, skipping
Installing RDoc documentation for builder-3.0.0...
unable to convert "\xF1" from ASCII-8BIT to UTF-8 for README, skipping
unable to convert "\xF1" from ASCII-8BIT to UTF-8 for README.rdoc, skipping

escaping bug in ri

I was trying to lookup the ri for []:

DB:~ $ ri []
/opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:744: warning: character class has ']' without escape: /^[][^:]*$/
/opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:744:in `block (2 levels) in expand_class': premature end of char-class: /^[][^:]*$/ (RegexpError)
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:743:in `select'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:743:in `block in expand_class'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:739:in `each'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:739:in `inject'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:739:in `expand_class'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:766:in `expand_name'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:728:in `block in display_names'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:727:in `each'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:727:in `display_names'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:1128:in `run'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:324:in `run'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/bin/ri:5:in `<top (required)>'
    from /opt/local/bin/ri:19:in `load'
    from /opt/local/bin/ri:19:in `<main>'
DB:~ $ ri \[\]
/opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:744: warning: character class has ']' without escape: /^[][^:]*$/
/opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:744:in `block (2 levels) in expand_class': premature end of char-class: /^[][^:]*$/ (RegexpError)
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:743:in `select'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:743:in `block in expand_class'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:739:in `each'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:739:in `inject'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:739:in `expand_class'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:766:in `expand_name'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:728:in `block in display_names'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:727:in `each'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:727:in `display_names'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:1128:in `run'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/lib/rdoc/ri/driver.rb:324:in `run'
    from /opt/local/lib/ruby1.9/gems/1.9.1/gems/rdoc-3.8/bin/ri:5:in `<top (required)>'
    from /opt/local/bin/ri:19:in `load'
    from /opt/local/bin/ri:19:in `<main>'

rdoc does not track C externs for classes/modules

When a *.c file describes a class, with methods, etc., and a *.rb exists owning the same class name, then the *.rb wins completely.

Example: ext/fiddle/closure.c and ext/fiddle/lib/fiddle/closure.rb
The *.c includes two methods, but when the documentation is generated, on the the attributes described in the *.rb are present for the Fiddle::Closure class.

rdoc-data --install fails on Windows

For a newly installed Ruby + Ruby Gems installation on Windows, while running 'gem update', I got this:

Fetching: rdoc-3.5.3.gem (100%)
NOTE: If you are running Ruby 1.9.2 you can ignore this message.

RDoc 2.5+ has a new ri data format for Ruby 1.8.7 and 1.9.1.  (1.9.2 contains
RDoc 2.5 so there is nothing to do!)

To install new ri data for core and stdlib you'll need to:

  gem install rdoc-data

then run:

  rdoc-data --install

.. for which I ran 'gem install rdoc-data' since it seemed safe enough, and then 'rdoc-data-2.5.3':

C:\Users\jdavis>gem install rdoc-data
Fetching: rdoc-data-2.5.3.gem (100%)
To install ri data for RDoc 2.5+ run:

  rdoc-data

Successfully installed rdoc-data-2.5.3
1 gem installed
Installing ri documentation for rdoc-data-2.5.3...
Installing RDoc documentation for rdoc-data-2.5.3...

C:\Users\jdavis>rdoc-data --install
C:/Ruby/lib/ruby/1.9.1/fileutils.rb:121:in `chdir': No such file or directory -
C:/Ruby/lib/ruby/gems/1.9.1/gems/rdoc-data-2.5.3/data/1.9.2 (Errno::ENOENT)
        from C:/Ruby/lib/ruby/1.9.1/fileutils.rb:121:in `cd'
        from C:/Ruby/lib/ruby/gems/1.9.1/gems/rdoc-data-2.5.3/lib/rdoc/data.rb:5
2:in `run'
        from C:/Ruby/lib/ruby/gems/1.9.1/gems/rdoc-data-2.5.3/lib/rdoc/data.rb:4
1:in `run'
        from C:/Ruby/lib/ruby/gems/1.9.1/gems/rdoc-data-2.5.3/bin/rdoc-data:6:in
 `<top (required)>'
        from C:/Ruby/bin/rdoc-data:19:in `load'
        from C:/Ruby/bin/rdoc-data:19:in `<main>'

C:\Users\jdavis>

'undefined method `gsub' for nil:NilClass' while installing clbustos-rtf-0.4.2

Tried to install clbustos-rtf gem:

RubyFin-MacBook-Pro:~ rubyfin$ gem install clbustos-rtf
Successfully installed clbustos-rtf-0.4.2
1 gem installed
Installing ri documentation for clbustos-rtf-0.4.2...
Installing RDoc documentation for clbustos-rtf-0.4.2...
ERROR: While generating documentation for clbustos-rtf-0.4.2
... MESSAGE: Error while evaluating /Users/rubyfin/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/1.9.1/rdoc/generator/template/darkfish/classpage.rhtml: undefined method `gsub' for nil:NilClass (at ""method-source-code"\n\t\t\t\t\t\tid="new-source">\n

\n")

... RDOC args: --op /Users/rubyfin/.rvm/gems/ruby-1.9.2-p180/doc/clbustos-rtf-0.4.2/rdoc lib LICENSE README.rdoc --title clbustos-rtf-0.4.2 Documentation --quiet

ERROR: While generating documentation for activesupport-3.1.0.rc3

After installing rails rc2, which turns out to be rc3... I got the following error

Installing RDoc documentation for activesupport-3.1.0.rc3...
ERROR: While generating documentation for activesupport-3.1.0.rc3
... MESSAGE: incompatible character encodings: UTF-8 and ASCII-8BIT
... RDOC args: --op /Users/paulgisbourne/.rvm/gems/ruby-1.9.2-p180/doc/activesupport-3.1.0.rc3/rdoc lib --title activesupport-3.1.0.rc3 Documentation --quiet

My rails version is saying - Rails 3.1.0.rc3

ri cache file should contain the encoding

Also, ri should warn if the locale and the ri data encoding do not match and conversion may not be possible.

RDoc parser error on gem update

Not sure if this error really pertains to RDoc or not, but the link from running a 'gem update' on OSX 10.6.8, it lead me to file a bug report here.

Below is the trace (also includes RDoc and Ruby versions):

Installing ri documentation for bundler-1.0.15...
While parsing markup, RDoc encountered a RDoc::Markup::Parser::ParseError:

expected NEWLINE got [:BULLET, "*", 0, 2]
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/markup/parser.rb:378:in `skip'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/markup/parser.rb:91:in `build_heading'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/markup/parser.rb:337:in `parse'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/markup/parser.rb:61:in `parse'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/text.rb:111:in `parse'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/any_method.rb:94:in `marshal_dump'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/ri/store.rb:350:in `dump'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/ri/store.rb:350:in `save_method'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/generator/ri.rb:45:in `generate'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/context.rb:762:in `each_method'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/context.rb:762:in `each'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/context.rb:762:in `each_method'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/generator/ri.rb:43:in `generate'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/generator/ri.rb:38:in `each'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/generator/ri.rb:38:in `generate'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/rdoc.rb:478:in `generate'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/rdoc.rb:470:in `chdir'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/rdoc.rb:470:in `generate'
    from /Library/Ruby/Gems/1.8/gems/rdoc-3.9/lib/rdoc/rdoc.rb:453:in `document'
    from /Library/Ruby/Site/1.8/rubygems/doc_manager.rb:189:in `run_rdoc'
    from /Library/Ruby/Site/1.8/rubygems/doc_manager.rb:156:in `install_ri'
    from /Library/Ruby/Site/1.8/rubygems/doc_manager.rb:116:in `generate_ri'
    from /Library/Ruby/Site/1.8/rubygems/commands/update_command.rb:86:in `execute'
    from /Library/Ruby/Site/1.8/rubygems/commands/update_command.rb:85:in `each'
    from /Library/Ruby/Site/1.8/rubygems/commands/update_command.rb:85:in `execute'
    from /Library/Ruby/Site/1.8/rubygems/command.rb:278:in `invoke'
    from /Library/Ruby/Site/1.8/rubygems/command_manager.rb:147:in `process_args'
    from /Library/Ruby/Site/1.8/rubygems/command_manager.rb:117:in `run'
    from /Library/Ruby/Site/1.8/rubygems/gem_runner.rb:65:in `run'
    from /usr/bin/gem:21

---8<---
How does the new system work?
===
* Load information from Gemfile and Lockfile
* Invalidate stale locked specs
  * All specs from stale source are stale
  * All specs that are reachable only through a stale
    dependency are stale.
* If all fresh dependencies are satisfied by the locked
  specs, then we can try to resolve locally.
---8<---

RDoc 3.9

Ruby 1.8.7-p174 2009-06-12

Please file a bug report with the above information at:

http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse

ERROR:  While generating documentation for bundler-1.0.15
... MESSAGE:   expected NEWLINE got [:BULLET, "*", 0, 2]
... RDOC args: --ri --op /Library/Ruby/Gems/1.8/doc/bundler-1.0.15/ri lib --title bundler-1.0.15 Documentation --quiet

Any way to generate documentation without source ?

Is there a way to decouple the documentation from the code ? I'm principally thinking of ways to improve the ruby documentation without having to wait for an official release. This ticket is also for me, I'll update it if I find something.

rdoc failed when parsing UTF-8 script

Hello

rdoc failed when parsing UTF-8 ruby script. I fix it with the following patch. Please ally it, as is or rework as you want to allow proceeding the UTF-8 ruby scripts:

cat ruby_lex.rb.diff

--- ruby_lex.rb 2011-03-19 03:10:32.340220572 +0300
+++ /usr/share/ruby/1.9/rdoc/ruby_lex.rb 2011-03-19 04:12:27.188068372 +0300
@@ -196,7 +196,7 @@ class RDoc::RubyLex
end

def peek_equal?(str)

• chrs = str.split(//)
• chrs = str.unpack('U*').map do |x| x.chr(Encoding::UTF_8) end
  until @rests.size >= chrs.size
  return false unless buf_input
  end
  @@ -221,7 +221,7 @@ class RDoc::RubyLex
  prompt
  line = @input.call
  return nil unless line
• @rests.concat line.split(//)
• @rests.concat(line.unpack('U*').map do |x| x.chr(Encoding::UTF_8) end)
  true
  end
  private :buf_input

Constant that refers to classname appears in doc even when #:nodoc:'d

class Jobo
 A_CONS = 1 # :nodoc:
 J=Jobo # :nodoc:

 def foo
   'foo'
 end
end

in the resulting output J will still appear as a constant in the docs. A_CONS will not. This was found in the wild in ruby/lib/e2mmap.rb.