rdoc 4.0.1 → 4.1.0.preview.3

data/lib/rdoc/ruby_token.rb

@@ -276,50 +276,50 @@ module RDoc::RubyToken
   end
 
   TokenDefinitions = [
-    [:TkCLASS,      TkKW,  "class",  EXPR_CLASS],
-    [:TkMODULE,     TkKW,  "module", EXPR_BEG],
-    [:TkDEF,        TkKW,  "def",    EXPR_FNAME],
-    [:TkUNDEF,      TkKW,  "undef",  EXPR_FNAME],
-    [:TkBEGIN,      TkKW,  "begin",  EXPR_BEG],
-    [:TkRESCUE,     TkKW,  "rescue", EXPR_MID],
-    [:TkENSURE,     TkKW,  "ensure", EXPR_BEG],
-    [:TkEND,        TkKW,  "end",    EXPR_END],
-    [:TkIF,         TkKW,  "if",     EXPR_BEG, :TkIF_MOD],
-    [:TkUNLESS,     TkKW,  "unless", EXPR_BEG, :TkUNLESS_MOD],
-    [:TkTHEN,       TkKW,  "then",   EXPR_BEG],
-    [:TkELSIF,      TkKW,  "elsif",  EXPR_BEG],
-    [:TkELSE,       TkKW,  "else",   EXPR_BEG],
-    [:TkCASE,       TkKW,  "case",   EXPR_BEG],
-    [:TkWHEN,       TkKW,  "when",   EXPR_BEG],
-    [:TkWHILE,      TkKW,  "while",  EXPR_BEG, :TkWHILE_MOD],
-    [:TkUNTIL,      TkKW,  "until",  EXPR_BEG, :TkUNTIL_MOD],
-    [:TkFOR,        TkKW,  "for",    EXPR_BEG],
-    [:TkBREAK,      TkKW,  "break",  EXPR_MID],
-    [:TkNEXT,       TkKW,  "next",   EXPR_END],
-    [:TkREDO,       TkKW,  "redo",   EXPR_END],
-    [:TkRETRY,      TkKW,  "retry",  EXPR_END],
-    [:TkIN,         TkKW,  "in",     EXPR_BEG],
-    [:TkDO,         TkKW,  "do",     EXPR_BEG],
-    [:TkRETURN,     TkKW,  "return", EXPR_MID],
-    [:TkYIELD,      TkKW,  "yield",  EXPR_END],
-    [:TkSUPER,      TkKW,  "super",  EXPR_END],
-    [:TkSELF,       TkKW,  "self",   EXPR_END],
-    [:TkNIL,        TkKW,  "nil",    EXPR_END],
-    [:TkTRUE,       TkKW,  "true",   EXPR_END],
-    [:TkFALSE,      TkKW,  "false",  EXPR_END],
-    [:TkAND,        TkKW,  "and",    EXPR_BEG],
-    [:TkOR,         TkKW,  "or",     EXPR_BEG],
-    [:TkNOT,        TkKW,  "not",    EXPR_BEG],
+    [:TkCLASS,      TkKW,  "class",  :EXPR_CLASS],
+    [:TkMODULE,     TkKW,  "module", :EXPR_BEG],
+    [:TkDEF,        TkKW,  "def",    :EXPR_FNAME],
+    [:TkUNDEF,      TkKW,  "undef",  :EXPR_FNAME],
+    [:TkBEGIN,      TkKW,  "begin",  :EXPR_BEG],
+    [:TkRESCUE,     TkKW,  "rescue", :EXPR_MID],
+    [:TkENSURE,     TkKW,  "ensure", :EXPR_BEG],
+    [:TkEND,        TkKW,  "end",    :EXPR_END],
+    [:TkIF,         TkKW,  "if",     :EXPR_BEG, :TkIF_MOD],
+    [:TkUNLESS,     TkKW,  "unless", :EXPR_BEG, :TkUNLESS_MOD],
+    [:TkTHEN,       TkKW,  "then",   :EXPR_BEG],
+    [:TkELSIF,      TkKW,  "elsif",  :EXPR_BEG],
+    [:TkELSE,       TkKW,  "else",   :EXPR_BEG],
+    [:TkCASE,       TkKW,  "case",   :EXPR_BEG],
+    [:TkWHEN,       TkKW,  "when",   :EXPR_BEG],
+    [:TkWHILE,      TkKW,  "while",  :EXPR_BEG, :TkWHILE_MOD],
+    [:TkUNTIL,      TkKW,  "until",  :EXPR_BEG, :TkUNTIL_MOD],
+    [:TkFOR,        TkKW,  "for",    :EXPR_BEG],
+    [:TkBREAK,      TkKW,  "break",  :EXPR_MID],
+    [:TkNEXT,       TkKW,  "next",   :EXPR_END],
+    [:TkREDO,       TkKW,  "redo",   :EXPR_END],
+    [:TkRETRY,      TkKW,  "retry",  :EXPR_END],
+    [:TkIN,         TkKW,  "in",     :EXPR_BEG],
+    [:TkDO,         TkKW,  "do",     :EXPR_BEG],
+    [:TkRETURN,     TkKW,  "return", :EXPR_MID],
+    [:TkYIELD,      TkKW,  "yield",  :EXPR_END],
+    [:TkSUPER,      TkKW,  "super",  :EXPR_END],
+    [:TkSELF,       TkKW,  "self",   :EXPR_END],
+    [:TkNIL,        TkKW,  "nil",    :EXPR_END],
+    [:TkTRUE,       TkKW,  "true",   :EXPR_END],
+    [:TkFALSE,      TkKW,  "false",  :EXPR_END],
+    [:TkAND,        TkKW,  "and",    :EXPR_BEG],
+    [:TkOR,         TkKW,  "or",     :EXPR_BEG],
+    [:TkNOT,        TkKW,  "not",    :EXPR_BEG],
     [:TkIF_MOD,     TkKW],
     [:TkUNLESS_MOD, TkKW],
     [:TkWHILE_MOD,  TkKW],
     [:TkUNTIL_MOD,  TkKW],
-    [:TkALIAS,      TkKW,  "alias",    EXPR_FNAME],
-    [:TkDEFINED,    TkKW,  "defined?", EXPR_END],
-    [:TklBEGIN,     TkKW,  "BEGIN",    EXPR_END],
-    [:TklEND,       TkKW,  "END",      EXPR_END],
-    [:Tk__LINE__,   TkKW,  "__LINE__", EXPR_END],
-    [:Tk__FILE__,   TkKW,  "__FILE__", EXPR_END],
+    [:TkALIAS,      TkKW,  "alias",    :EXPR_FNAME],
+    [:TkDEFINED,    TkKW,  "defined?", :EXPR_END],
+    [:TklBEGIN,     TkKW,  "BEGIN",    :EXPR_END],
+    [:TklEND,       TkKW,  "END",      :EXPR_END],
+    [:Tk__LINE__,   TkKW,  "__LINE__", :EXPR_END],
+    [:Tk__FILE__,   TkKW,  "__FILE__", :EXPR_END],
 
     [:TkIDENTIFIER, TkId],
     [:TkFID,        TkId],
@@ -335,6 +335,7 @@ module RDoc::RubyToken
     [:TkXSTRING,    TkVal],
     [:TkREGEXP,     TkVal],
     [:TkSYMBOL,     TkVal],
+    [:TkCHAR,       TkVal],
 
     [:TkDSTRING,    TkNode],
     [:TkDXSTRING,   TkNode],

data/lib/rdoc/servlet.rb

@@ -124,6 +124,10 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
     else
       show_documentation req, res
     end
+  rescue WEBrick::HTTPStatus::NotFound => e
+    generator = generator_for RDoc::Store.new
+
+    not_found generator, req, res, e.message
   rescue WEBrick::HTTPStatus::Status
     raise
   rescue => e
@@ -300,8 +304,9 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
   ##
   # Returns a 404 page built by +generator+ for +req+ on +res+.
 
-  def not_found generator, req, res
-    res.body = generator.generate_servlet_not_found req.path
+  def not_found generator, req, res, message = nil
+    message ||= "The page <kbd>#{ERB::Util.h req.path}</kbd> was not found"
+    res.body = generator.generate_servlet_not_found message
     res.status = 404
   end
 
@@ -419,11 +424,16 @@ version.  If you're viewing Ruby's documentation, include the version of ruby.
         source_name == dir[%r%/([^/]*)/ri$%, 1]
       end
 
-      raise RDoc::Error,
-            "could not find ri documentation for #{source_name}" unless
-        ri_dir
+      raise WEBrick::HTTPStatus::NotFound,
+            "Could not find gem \"#{source_name}\". Are you sure you installed it?" unless ri_dir
+
+      store = RDoc::Store.new ri_dir, type
+
+      return store if File.exist? store.cache_path
+
+      raise WEBrick::HTTPStatus::NotFound,
+            "Could not find documentation for \"#{source_name}\". Please run `gem rdoc --ri gem_name`"
 
-      RDoc::Store.new ri_dir, type
     end
   end
 

data/lib/rdoc/stats.rb

@@ -187,12 +187,12 @@ class RDoc::Stats
   # A report that says you did a great job!
 
   def great_job
-    report = []
-    report << '100% documentation!'
-    report << nil
-    report << 'Great Job!'
+    report = RDoc::Markup::Document.new
+
+    report << RDoc::Markup::Paragraph.new('100% documentation!')
+    report << RDoc::Markup::Paragraph.new('Great Job!')
 
-    report.join "\n"
+    report
   end
 
   ##
@@ -217,8 +217,6 @@ class RDoc::Stats
       extend RDoc::Text
     end
 
-    report = []
-
     if @coverage_level.zero? then
       calculate
 
@@ -227,14 +225,20 @@ class RDoc::Stats
 
     ucm = @store.unique_classes_and_modules
 
+    report = RDoc::Markup::Document.new
+    report << RDoc::Markup::Paragraph.new('The following items are not documented:')
+    report << RDoc::Markup::BlankLine.new
+
     ucm.sort.each do |cm|
-      report << report_class_module(cm) {
+      body = report_class_module(cm) {
         [
           report_constants(cm),
           report_attributes(cm),
           report_methods(cm),
         ].compact
       }
+
+      report << body if body
     end
 
     if @coverage_level > 0 then
@@ -243,10 +247,7 @@ class RDoc::Stats
       return great_job if @num_items == @doc_items
     end
 
-    report.unshift nil
-    report.unshift 'The following items are not documented:'
-
-    report.join "\n"
+    report
   end
 
   ##
@@ -260,7 +261,8 @@ class RDoc::Stats
     cm.each_attribute do |attr|
       next if attr.documented?
       line = attr.line ? ":#{attr.line}" : nil
-      report << "  #{attr.definition} :#{attr.name} # in file #{attr.file.full_name}#{line}"
+      report << "  #{attr.definition} :#{attr.name} # in file #{attr.file.full_name}#{line}\n"
+      report << "\n"
     end
 
     report
@@ -273,38 +275,47 @@ class RDoc::Stats
     return if cm.fully_documented? and @coverage_level.zero?
     return unless cm.display?
 
-    report = []
+    report = RDoc::Markup::Document.new
 
     if cm.in_files.empty? then
-      report << "# #{cm.definition} is referenced but empty."
-      report << "#"
-      report << "# It probably came from another project.  I'm sorry I'm holding it against you."
-      report << nil
+      report << RDoc::Markup::Paragraph.new("#{cm.definition} is referenced but empty.")
+      report << RDoc::Markup::Paragraph.new("It probably came from another project.  I'm sorry I'm holding it against you.")
 
       return report
     elsif cm.documented? then
       documented = true
-      report << "#{cm.definition} # is documented"
+      klass = RDoc::Markup::Verbatim.new("#{cm.definition} # is documented\n")
     else
-      report << '# in files:'
+      report << RDoc::Markup::Paragraph.new('In files:')
+
+      list = RDoc::Markup::List.new :BULLET
 
       cm.in_files.each do |file|
-        report << "#   #{file.full_name}"
+        para = RDoc::Markup::Paragraph.new file.full_name
+        list << RDoc::Markup::ListItem.new(nil, para)
       end
 
-      report << nil
+      report << list
+      report << RDoc::Markup::BlankLine.new
 
-      report << "#{cm.definition}"
+      klass = RDoc::Markup::Verbatim.new("#{cm.definition}\n")
     end
 
+    klass << "\n"
+
     body = yield.flatten # HACK remove #flatten
 
-    return if body.empty? and documented
+    if body.empty? then
+      return if documented
+
+      klass.parts.pop
+    else
+      klass.parts.concat body
+    end
 
-    report << nil << body unless body.empty?
+    klass << "end\n"
 
-    report << 'end'
-    report << nil
+    report << klass
 
     report
   end
@@ -323,8 +334,9 @@ class RDoc::Stats
       next if constant.documented? || constant.is_alias_for
 
       line = constant.line ? ":#{constant.line}" : line
-      report << "  # in file #{constant.file.full_name}#{line}"
-      report << "  #{constant.name} = nil"
+      report << "  # in file #{constant.file.full_name}#{line}\n"
+      report << "  #{constant.name} = nil\n"
+      report << "\n"
     end
 
     report
@@ -350,7 +362,7 @@ class RDoc::Stats
           @undoc_params += undoc.length
 
           undoc = undoc.map do |param| "+#{param}+" end
-          param_report = "  # #{undoc.join ', '} is not documented"
+          param_report = "  # #{undoc.join ', '} is not documented\n"
         end
       end
 
@@ -359,10 +371,10 @@ class RDoc::Stats
       line = method.line ? ":#{method.line}" : nil
       scope = method.singleton ? 'self.' : nil
 
-      report << "  # in file #{method.file.full_name}#{line}"
+      report << "  # in file #{method.file.full_name}#{line}\n"
       report << param_report if param_report
-      report << "  def #{scope}#{method.name}#{method.params}; end"
-      report << nil
+      report << "  def #{scope}#{method.name}#{method.params}; end\n"
+      report << "\n"
     end
 
     report
@@ -385,35 +397,36 @@ class RDoc::Stats
       @undoc_params,
     ].max.to_s.length
 
-    report = []
-    report << 'Files:      %*d' % [num_width, @num_files]
+    report = RDoc::Markup::Verbatim.new
+
+    report << "Files:      %*d\n" % [num_width, @num_files]
 
-    report << nil
+    report << "\n"
 
-    report << 'Classes:    %*d (%*d undocumented)' % [
+    report << "Classes:    %*d (%*d undocumented)\n" % [
       num_width, @num_classes, undoc_width, @undoc_classes]
-    report << 'Modules:    %*d (%*d undocumented)' % [
+    report << "Modules:    %*d (%*d undocumented)\n" % [
       num_width, @num_modules, undoc_width, @undoc_modules]
-    report << 'Constants:  %*d (%*d undocumented)' % [
+    report << "Constants:  %*d (%*d undocumented)\n" % [
       num_width, @num_constants, undoc_width, @undoc_constants]
-    report << 'Attributes: %*d (%*d undocumented)' % [
+    report << "Attributes: %*d (%*d undocumented)\n" % [
       num_width, @num_attributes, undoc_width, @undoc_attributes]
-    report << 'Methods:    %*d (%*d undocumented)' % [
+    report << "Methods:    %*d (%*d undocumented)\n" % [
       num_width, @num_methods, undoc_width, @undoc_methods]
-    report << 'Parameters: %*d (%*d undocumented)' % [
+    report << "Parameters: %*d (%*d undocumented)\n" % [
       num_width, @num_params, undoc_width, @undoc_params] if
         @coverage_level > 0
 
-    report << nil
+    report << "\n"
 
-    report << 'Total:      %*d (%*d undocumented)' % [
+    report << "Total:      %*d (%*d undocumented)\n" % [
       num_width, @num_items, undoc_width, @undoc_items]
 
-    report << '%6.2f%% documented' % percent_doc
-    report << nil
-    report << 'Elapsed: %0.1fs' % (Time.now - @start)
+    report << "%6.2f%% documented\n" % percent_doc
+    report << "\n"
+    report << "Elapsed: %0.1fs\n" % (Time.now - @start)
 
-    report.join "\n"
+    RDoc::Markup::Document.new report
   end
 
   ##

data/lib/rdoc/store.rb

@@ -305,8 +305,10 @@ class RDoc::Store
     # cache included modules before they are removed from the documentation
     all_classes_and_modules.each { |cm| cm.ancestors }
 
-    remove_nodoc @classes_hash
-    remove_nodoc @modules_hash
+    unless min_visibility == :nodoc then
+      remove_nodoc @classes_hash
+      remove_nodoc @modules_hash
+    end
 
     @unique_classes = find_unique @classes_hash
     @unique_modules = find_unique @modules_hash
@@ -661,7 +663,7 @@ class RDoc::Store
   end
 
   ##
-  # Converts the variable => ClassModule map +variables+ from a C parser into 
+  # Converts the variable => ClassModule map +variables+ from a C parser into
   # a variable => class name map.
 
   def make_variable_map variables

data/lib/rdoc/test_case.rb

@@ -1,4 +1,11 @@
 require 'rubygems'
+
+begin
+  gem 'minitest', '~> 4.0' unless defined?(Test::Unit)
+rescue NoMethodError
+  # for ruby tests
+end
+
 require 'minitest/autorun'
 require 'minitest/benchmark' if ENV['BENCHMARK']
 
@@ -45,6 +52,7 @@ class RDoc::TestCase < MiniTest::Unit::TestCase
 
     @rdoc = RDoc::RDoc.new
     @rdoc.store = @store
+    @rdoc.options = RDoc::Options.new
 
     g = Object.new
     def g.class_dir() end
@@ -52,6 +60,27 @@ class RDoc::TestCase < MiniTest::Unit::TestCase
     @rdoc.generator = g
   end
 
+  ##
+  # Asserts +path+ is a file
+
+  def assert_file path
+    assert File.file?(path), "#{path} is not a file"
+  end
+
+  ##
+  # Asserts +path+ is a directory
+
+  def assert_directory path
+    assert File.directory?(path), "#{path} is not a directory"
+  end
+
+  ##
+  # Refutes +path+ exists
+
+  def refute_file path
+    refute File.exist?(path), "#{path} exists"
+  end
+
   ##
   # Shortcut for RDoc::Markup::BlankLine.new
 
@@ -109,6 +138,16 @@ class RDoc::TestCase < MiniTest::Unit::TestCase
     @RM::List.new type, *items
   end
 
+  ##
+  # Enables pretty-print output
+
+  def mu_pp obj # :nodoc:
+    s = ''
+    s = PP.pp obj, s
+    s = s.force_encoding Encoding.default_external if defined? Encoding
+    s.chomp
+  end
+
   ##
   # Shortcut for RDoc::Markup::Paragraph.new with +contents+
 

data/lib/rdoc/tom_doc.rb

@@ -129,7 +129,8 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   def initialize
     super
 
-    @section = nil
+    @section      = nil
+    @seen_returns = false
   end
 
   # Internal: Builds a heading from the token stream
@@ -147,7 +148,7 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   end
 
   # Internal: Builds a verbatim from the token stream.  A verbatim in the
-  # Examples section will be marked as in ruby format.
+  # Examples section will be marked as in Ruby format.
   #
   # margin - The indentation from the margin for lines that belong to this
   #          verbatim section.
@@ -176,9 +177,17 @@ class RDoc::TomDoc < RDoc::Markup::Parser
     until @tokens.empty? do
       type, data, = get
 
-      if type == :TEXT then
+      case type
+      when :TEXT then
+        @section = 'Returns' if data =~ /\AReturns/
+
         paragraph << data
-        skip :NEWLINE
+      when :NEWLINE then
+        if :TEXT == peek_token[0] then
+          paragraph << ' '
+        else
+          break
+        end
       else
         unget
         break
@@ -190,6 +199,21 @@ class RDoc::TomDoc < RDoc::Markup::Parser
     paragraph
   end
 
+  ##
+  # Detects a section change to "Returns" and adds a heading
+
+  def parse_text parent, indent # :nodoc:
+    paragraph = build_paragraph indent
+
+    if false == @seen_returns and 'Returns' == @section then
+      @seen_returns = true
+      parent << RDoc::Markup::Heading.new(3, 'Returns')
+      parent << RDoc::Markup::BlankLine.new
+    end
+
+    parent << paragraph
+  end
+
   # Internal: Turns text into an Array of tokens
   #
   # text - A String containing TomDoc-format text.