rdoc 3.2 → 3.3

data/lib/rdoc/rdoc.rb

@@ -197,6 +197,7 @@ option)
       end unless @options.force_output
     else
       FileUtils.mkdir_p dir
+      FileUtils.touch output_flag_file dir
     end
 
     last
@@ -416,10 +417,13 @@ The internal error was:
 
     RDoc::TopLevel.complete @options.visibility
 
+    @stats.coverage_level = @options.coverage_report
+
     if @options.coverage_report then
       puts
+
       puts @stats.report
-    elsif file_info.empty?
+    elsif file_info.empty? then
       $stderr.puts "\nNo newer files." unless @options.quiet
     else
       gen_klass = @options.generator

data/lib/rdoc/ri/driver.rb

@@ -651,12 +651,14 @@ Options may also be set in the 'RI' environment variable.
 
     raise NotFoundError, name if found.empty?
 
+    filtered = filter_methods found, name
+
     out = RDoc::Markup::Document.new
 
     out << RDoc::Markup::Heading.new(1, name)
     out << RDoc::Markup::BlankLine.new
 
-    found.each do |store, methods|
+    filtered.each do |store, methods|
       methods.each do |method|
         out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")
 
@@ -753,6 +755,21 @@ Options may also be set in the 'RI' environment variable.
     "#{expand_class klass}#{selector}#{method}"
   end
 
+  ##
+  # Filters the methods in +found+ trying to find a match for +name+.
+
+  def filter_methods found, name
+    regexp = name_regexp name
+
+    filtered = found.find_all do |store, methods|
+      methods.any? { |method| method.full_name =~ regexp }
+    end
+
+    return filtered unless filtered.empty?
+
+    found
+  end
+
   ##
   # Yields items matching +name+ including the store they were found in, the
   # class being searched for, the class they were found in (an ancestor) the
@@ -948,10 +965,10 @@ Options may also be set in the 'RI' environment variable.
       methods = []
 
       methods << load_method(store, :class_methods, ancestor, '::',  method) if
-        types == :class or types == :both
+        [:class, :both].include? types
 
       methods << load_method(store, :instance_methods, ancestor, '#',  method) if
-        types == :instance or types == :both
+        [:instance, :both].include? types
 
       found << [store, methods.compact]
     end
@@ -970,6 +987,21 @@ Options may also be set in the 'RI' environment variable.
     end
   end
 
+  ##
+  # Returns a regular expression for +name+ that will match an
+  # RDoc::AnyMethod's name.
+
+  def name_regexp name
+    klass, type, name = parse_name name
+
+    case type
+    when '#', '::' then
+      /^#{klass}#{type}#{name}$/
+    else
+      /^#{klass}(#|::)#{name}$/
+    end
+  end
+
   ##
   # Paginates output through a pager program.
 
@@ -996,7 +1028,7 @@ Options may also be set in the 'RI' environment variable.
   end
 
   ##
-  # Extract the class, selector and method name parts from +name+ like
+  # Extracts the class, selector and method name parts from +name+ like
   # Foo::Bar#baz.
   #
   # NOTE: Given Foo::Bar, Bar is considered a class even though it may be a

data/lib/rdoc/ruby_lex.rb

@@ -401,13 +401,15 @@ class RDoc::RubyLex
       |op, io|
       @ltype = "="
       res = ''
-      until (ch = getc) == "\n" do res << ch end
+      nil until (ch = getc) == "\n"
+
       until peek_equal?("=end") && peek(4) =~ /\s/ do
         until (ch = getc) == "\n" do res << ch end
       end
-      res << gets
+      gets # consume =end
+
       @ltype = nil
-      Token(TkRD_COMMENT, res)
+      Token(TkCOMMENT, res)
     end
 
     @OP.def_rule("\n") do |op, io|

data/lib/rdoc/single_class.rb

@@ -5,10 +5,19 @@ require 'rdoc/class_module'
 
 class RDoc::SingleClass < RDoc::ClassModule
 
+  ##
   # Adds the superclass to the included modules.
+
   def ancestors
     superclass ? super + [superclass] : super
   end
 
+  ##
+  # The definition of this singleton class, <tt>class << MyClassName</tt>
+
+  def definition
+    "class << #{full_name}"
+  end
+
 end
 

data/lib/rdoc/stats.rb

@@ -6,6 +6,11 @@ require 'rdoc'
 
 class RDoc::Stats
 
+  ##
+  # Output level for the coverage report
+
+  attr_reader :coverage_level
+
   ##
   # Count of files parsed during parsing
 
@@ -23,10 +28,13 @@ class RDoc::Stats
   def initialize num_files, verbosity = 1
     @files_so_far = 0
     @num_files = num_files
+
+    @coverage_level = 0
     @fully_documented = nil
+    @num_params = 0
     @percent_doc = nil
-
     @start = Time.now
+    @undoc_params = 0
 
     @display = case verbosity
                when 0 then Quiet.new   num_files
@@ -93,10 +101,11 @@ class RDoc::Stats
   end
 
   ##
-  # Calculates documentation totals and percentages
+  # Calculates documentation totals and percentages for classes, modules,
+  # constants, attributes and methods.
 
   def calculate
-    return if @percent_doc
+    return if @doc_items
 
     ucm = RDoc::TopLevel.unique_classes_and_modules
     constants = []
@@ -119,20 +128,31 @@ class RDoc::Stats
       @num_classes +
       @num_constants +
       @num_methods +
-      @num_modules
+      @num_modules +
+      @num_params
 
     @undoc_items =
       @undoc_attributes +
       @undoc_classes +
       @undoc_constants +
       @undoc_methods +
-      @undoc_modules
+      @undoc_modules +
+      @undoc_params
 
     @doc_items = @num_items - @undoc_items
+  end
 
-    @fully_documented = (@num_items - @doc_items) == 0
+  ##
+  # Sets coverage report level.  Accepted values are:
+  #
+  # false or nil:: No report
+  # 0:: Classes, modules, constants, attributes, methods
+  # 1:: Level 0 + method parameters
 
-    @percent_doc = @doc_items.to_f / @num_items * 100 if @num_items.nonzero?
+  def coverage_level= level
+    level = -1 unless level
+
+    @coverage_level = level
   end
 
   ##
@@ -159,97 +179,186 @@ class RDoc::Stats
     @fully_documented
   end
 
+  ##
+  # A report that says you did a great job!
+
+  def great_job
+    report = []
+    report << '100% documentation!'
+    report << nil
+    report << 'Great Job!'
+
+    report.join "\n"
+  end
+
+  ##
+  # Calculates the percentage of items documented.
+
+  def percent_doc
+    return @percent_doc if @percent_doc
+
+    @fully_documented = (@num_items - @doc_items) == 0
+
+    @percent_doc = @doc_items.to_f / @num_items * 100 if @num_items.nonzero?
+    @percent_doc ||= 0
+
+    @percent_doc
+  end
+
   ##
   # Returns a report on which items are not documented
 
   def report
+    if @coverage_level > 0 then
+      require 'rdoc/markup/to_tt_only'
+      require 'rdoc/generator/markup'
+      require 'rdoc/text'
+      extend RDoc::Text
+    end
+
     report = []
 
-    calculate
+    if @coverage_level.zero? then
+      calculate
+
+      return great_job if @num_items == @doc_items
+    end
+
+    ucm = RDoc::TopLevel.unique_classes_and_modules
+
+    ucm.sort.each do |cm|
+      report << report_class_module(cm) {
+        [
+          report_constants(cm),
+          report_attributes(cm),
+          report_methods(cm),
+        ].compact
+      }
+    end
+
+    if @coverage_level > 0 then
+      calculate
+
+      return great_job if @num_items == @doc_items
+    end
+
+    report.unshift nil
+    report.unshift 'The following items are not documented:'
+
+    report.join "\n"
+  end
+
+  ##
+  # Returns a report on undocumented attributes in ClassModule +cm+
+
+  def report_attributes cm
+    return if cm.attributes.empty?
+
+    report = []
+
+    cm.each_attribute do |attr|
+      next if attr.documented?
+      report << "  #{attr.definition} :#{attr.name} " \
+        "# in file #{attr.file.full_name}"
+    end
+
+    report
+  end
+
+  ##
+  # Returns a report on undocumented items in ClassModule +cm+
+
+  def report_class_module cm
+    return if cm.fully_documented? and @coverage_level.zero?
+
+    report = []
+
+    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
+
+      return report
+    elsif cm.documented? then
+      documented = true
+      report << "#{cm.definition} # is documented"
+    else
+      report << '# in files:'
+
+      cm.in_files.each do |file|
+        report << "#   #{file.full_name}"
+      end
 
-    if @num_items == @doc_items then
-      report << '100% documentation!'
       report << nil
-      report << 'Great Job!'
 
-      return report.join "\n"
+      report << "#{cm.definition}"
     end
 
-    report << 'The following items are not documented:'
+    body = yield.flatten # HACK remove #flatten
+
+    return if body.empty? and documented
+
+    report << nil << body unless body.empty?
+
+    report << 'end'
     report << nil
 
-    ucm = RDoc::TopLevel.unique_classes_and_modules
+    report
+  end
 
-    ucm.sort.each do |cm|
-      type = case cm # TODO #definition
-             when RDoc::NormalClass  then 'class'
-             when RDoc::SingleClass  then 'class <<'
-             when RDoc::NormalModule then 'module'
-             end
-
-      if cm.fully_documented? then
-        next
-      elsif cm.in_files.empty? or
-            (cm.constants.empty? and cm.method_list.empty?) then
-        report << "# #{type} #{cm.full_name} is referenced but empty."
-        report << '#'
-        report << '# It probably came from another project.  ' \
-                  'I\'m sorry I\'m holding it against you.'
-        report << nil
-
-        next
-      elsif cm.documented? then
-        report << "#{type} #{cm.full_name} # is documented"
-      else
-        report << '# in files:'
-
-        cm.in_files.each do |file|
-          report << "#   #{file.full_name}"
-        end
+  ##
+  # Returns a report on undocumented constants in ClassModule +cm+
 
-        report << nil
+  def report_constants cm
+    return if cm.constants.empty?
 
-        report << "#{type} #{cm.full_name}"
-      end
+    report = []
 
-      unless cm.constants.empty? then
-        report << nil
+    cm.each_constant do |constant|
+      # TODO constant aliases are listed in the summary but not reported
+      # figure out what to do here
+      next if constant.documented? || constant.is_alias_for
+      report << "  # in file #{constant.file.full_name}"
+      report << "  #{constant.name} = nil"
+    end
 
-        cm.each_constant do |constant|
-          # TODO constant aliases are listed in the summary but not reported
-          # figure out what to do here
-          next if constant.documented? || constant.is_alias_for
-          report << "  # in file #{constant.file.full_name}"
-          report << "  #{constant.name} = nil"
-        end
-      end
+    report
+  end
+
+  ##
+  # Returns a report on undocumented methods in ClassModule +cm+
 
-      unless cm.attributes.empty? then
-        report << nil
+  def report_methods cm
+    return if cm.method_list.empty?
 
-        cm.each_attribute do |attr|
-          next if attr.documented?
-          report << "  #{attr.definition} #{attr.name} " \
-                    "# in file #{attr.file.full_name}"
-        end
-      end
+    report = []
+
+    cm.each_method do |method|
+      next if method.documented? and @coverage_level.zero?
+
+      if @coverage_level > 0 then
+        params, undoc = undoc_params method
 
-      unless cm.method_list.empty? then
-        report << nil
+        @num_params += params
 
-        cm.each_method do |method|
-          next if method.documented?
-          report << "  # in file #{method.file.full_name}"
-          report << "  def #{method.name}#{method.params}; end"
-          report << nil
+        unless undoc.empty? then
+          @undoc_params += undoc.length
+
+          undoc = undoc.map do |param| "+#{param}+" end
+          param_report = "  # #{undoc.join ', '} is not documented"
         end
       end
 
-      report << 'end'
+      next if method.documented? and not param_report
+      report << "  # in file #{method.file.full_name}"
+      report << param_report if param_report
+      report << "  def #{method.name}#{method.params}; end"
       report << nil
     end
 
-    report.join "\n"
+    report
   end
 
   ##
@@ -259,13 +368,14 @@ class RDoc::Stats
     calculate
 
     num_width = [@num_files, @num_items].max.to_s.length
-    nodoc_width = [
+    undoc_width = [
       @undoc_attributes,
       @undoc_classes,
       @undoc_constants,
       @undoc_items,
       @undoc_methods,
       @undoc_modules,
+      @undoc_params,
     ].max.to_s.length
 
     report = []
@@ -274,28 +384,51 @@ class RDoc::Stats
     report << nil
 
     report << 'Classes:    %*d (%*d undocumented)' % [
-      num_width, @num_classes, nodoc_width, @undoc_classes]
+      num_width, @num_classes, undoc_width, @undoc_classes]
     report << 'Modules:    %*d (%*d undocumented)' % [
-      num_width, @num_modules, nodoc_width, @undoc_modules]
+      num_width, @num_modules, undoc_width, @undoc_modules]
     report << 'Constants:  %*d (%*d undocumented)' % [
-      num_width, @num_constants, nodoc_width, @undoc_constants]
+      num_width, @num_constants, undoc_width, @undoc_constants]
     report << 'Attributes: %*d (%*d undocumented)' % [
-      num_width, @num_attributes, nodoc_width, @undoc_attributes]
+      num_width, @num_attributes, undoc_width, @undoc_attributes]
     report << 'Methods:    %*d (%*d undocumented)' % [
-      num_width, @num_methods, nodoc_width, @undoc_methods]
+      num_width, @num_methods, undoc_width, @undoc_methods]
+    report << 'Parameters: %*d (%*d undocumented)' % [
+      num_width, @num_params, undoc_width, @undoc_params] if
+        @coverage_level > 0
 
     report << nil
 
     report << 'Total:      %*d (%*d undocumented)' % [
-      num_width, @num_items, nodoc_width, @undoc_items]
+      num_width, @num_items, undoc_width, @undoc_items]
 
-    report << '%6.2f%% documented' % @percent_doc if @percent_doc
+    report << '%6.2f%% documented' % percent_doc
     report << nil
     report << 'Elapsed: %0.1fs' % (Time.now - @start)
 
     report.join "\n"
   end
 
+  ##
+  # Determines which parametecs in +method+ were not documented.  Returns a
+  # total parameter count and an Array of undocumented methods.
+
+  def undoc_params method
+    @formatter ||= RDoc::Markup::ToTtOnly.new
+
+    params = method.param_list
+
+    return 0, [] if params.empty?
+
+    document = parse method.comment
+
+    tts = document.accept @formatter
+
+    undoc = params - tts
+
+    [params.length, undoc]
+  end
+
   autoload :Quiet,   'rdoc/stats/quiet'
   autoload :Normal,  'rdoc/stats/normal'
   autoload :Verbose, 'rdoc/stats/verbose'