Expand RDoc::Context#fully_documented? to include attributes

Expand documentation report to include attributes

Require minitest 2

Remove calls ::for for generators

100% documentation!

History.txt

@@ -7,8 +7,8 @@ Special thanks to Thierry Lambert for massive improvements to RDoc.
   * RDoc now converts input files to a single encoding specified by
     <tt>--encoding</tt>.  See RDoc::RDoc and RDoc::Options#encoding.
     <tt>--encoding</tt> is now preferred over <tt>--charset</tt>
-  * RDoc now supports a <tt>--coverage-report</tt> flag (also <tt>-C</tt>)
-    that outputs a report on items lacking documentation.
+  * RDoc now supports a <tt>--coverage-report</tt> flag (also <tt>-C</tt> and
+    <tt>--dcov</tt>) that outputs a report on items lacking documentation.
   * Templates (<tt>rdoc -T</tt>) are now checked for existence in
     RDoc::Options.  Generator authors can now use RDoc::Options#template_dir
     which is the full path to the template directory.
@@ -20,6 +20,7 @@ Special thanks to Thierry Lambert for massive improvements to RDoc.
     Lambert.
   * RDoc::Attr#type is now RDoc::Attr#definition.  Patch by Thierry Lambert.
   * Removed TimeConstantMethods
+  * RDoc now calls ::new instead of ::for on generators.
 * Minor enhancements
   * Added rdoc arguments <tt>--dry-run</tt>, <tt>--all</tt>,
     <tt>--visibility</tt>, <tt>--force-output</tt>, <tt>--hyperlink-all</tt>.

Rakefile

@@ -13,7 +13,7 @@ Hoe.spec 'rdoc' do
   self.remote_rdoc_dir = ''
   self.testlib = :minitest
 
-  extra_dev_deps   << ['minitest', '~> 1.3']
+  extra_dev_deps   << ['minitest', '~> 2']
   extra_rdoc_files << 'Rakefile'
   spec_extras['required_rubygems_version'] = '>= 1.3'
   spec_extras['homepage'] = 'http://rdoc.rubyforge.org'

lib/rdoc/context.rb

@@ -841,6 +841,7 @@ def full_name
 
   def fully_documented?
     documented? and
+      attributes.all? { |a| a.documented? } and
       method_list.all? { |m| m.documented? } and
       constants.all? { |c| c.documented? }
   end

lib/rdoc/generator/darkfish.rb

@@ -63,12 +63,6 @@ class RDoc::Generator::Darkfish
 
   VERSION = '2'
 
-  # Standard generator factory method
-
-  def self.for options
-    new options
-  end
-
   ##
   # Initialize a few instance variables before we start
 

lib/rdoc/generator/ri.rb

@@ -8,10 +8,6 @@ class RDoc::Generator::RI
 
   RDoc::RDoc.add_generator self
 
-  def self.for options
-    new options
-  end
-
   ##
   # Set up a new ri generator
 

lib/rdoc/markup.rb

@@ -527,6 +527,9 @@
 
 class RDoc::Markup
 
+  ##
+  # An AttributeManager which handles inline markup.
+
   attr_reader :attribute_manager
 
   ##

lib/rdoc/markup/attribute_manager.rb

@@ -15,9 +15,12 @@ class RDoc::Markup::AttributeManager
   # optimistic
   #++
 
-  A_PROTECT  = 004 # :nodoc:
+  A_PROTECT = 004 # :nodoc:
 
-  PROTECT_ATTR  = A_PROTECT.chr # :nodoc:
+  ##
+  # Special mask character to prevent inline markup handling
+
+  PROTECT_ATTR = A_PROTECT.chr # :nodoc:
 
   ##
   # This maps delimiters that occur around words (such as *bold* or +tt+)

lib/rdoc/markup/to_rdoc.rb

@@ -6,12 +6,39 @@
 
 class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
 
+  ##
+  # Current indent amount for output in characters
+
   attr_accessor :indent
+
+  ##
+  # Output width in characters
+
   attr_accessor :width
+
+  ##
+  # Stack of current list indexes for alphabetic and numeric lists
+
   attr_reader :list_index
+
+  ##
+  # Stack of list types
+
   attr_reader :list_type
+
+  ##
+  # Stack of list widths for indentation
+
   attr_reader :list_width
+
+  ##
+  # Prefix for the next list item.  See #use_prefix
+
   attr_reader :prefix
+
+  ##
+  # Output accumulator
+
   attr_reader :res
 
   ##

lib/rdoc/parser.rb

@@ -43,7 +43,15 @@ class RDoc::Parser
   @parsers = []
 
   class << self
+
+    ##
+    # A Hash that maps file exetensions regular expressions to parsers that
+    # will consume them.
+    #
+    # Use parse_files_matching to register a parser's file extensions.
+
     attr_reader :parsers
+
   end
 
   ##

lib/rdoc/parser/c.rb

@@ -137,6 +137,9 @@ def initialize(top_level, file_name, content, options, stats)
     @file_dir = File.dirname(@file_name)
   end
 
+  ##
+  # Scans #content for rb_define_alias
+
   def do_aliases
     @content.scan(/rb_define_alias\s*\(
                    \s*(\w+),
@@ -158,6 +161,9 @@ def do_aliases
     end
   end
 
+  ##
+  # Scans #content for rb_attr and rb_define_attr
+
   def do_attrs
     @content.scan(/rb_attr\s*\(
                    \s*(\w+),
@@ -178,6 +184,10 @@ def do_attrs
     end
   end
 
+  ##
+  # Scans #content for rb_define_module, rb_define_class, boot_defclass,
+  # rb_define_module_under, rb_define_class_under and rb_singleton_class
+
   def do_classes
     @content.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do
       |var_name, class_name|
@@ -224,6 +234,10 @@ def do_classes
     end
   end
 
+  ##
+  # Scans #content for rb_define_variable, rb_define_readonly_variable,
+  # rb_define_const and rb_define_global_const
+
   def do_constants
     @content.scan(%r%\Wrb_define_
                    ( variable          |
@@ -241,9 +255,7 @@ def do_constants
   end
 
   ##
-  # Look for includes of the form:
-  #
-  #   rb_include_module(rb_cArray, rb_mEnumerable);
+  # Scans #content for rb_include_module
 
   def do_includes
     @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
@@ -254,6 +266,11 @@ def do_includes
     end
   end
 
+  ##
+  # Scans #content for rb_define_method, rb_define_singleton_method,
+  # rb_define_module_function, rb_define_private_method,
+  # rb_define_global_function and define_filetest_function
+
   def do_methods
     @content.scan(%r%rb_define_
                    (
@@ -300,6 +317,10 @@ def do_methods
     end
   end
 
+  ##
+  # Finds the comment for an alias on +class_name+ from +new_name+ to
+  # +old_name+
+
   def find_alias_comment class_name, new_name, old_name
     content =~ %r%((?>/\*.*?\*/\s+))
                   rb_define_alias\(\s*#{Regexp.escape class_name}\s*,
@@ -412,6 +433,9 @@ def find_body(class_name, meth_name, meth_obj, body, quiet = false)
     true
   end
 
+  ##
+  # Finds a RDoc::NormalClass or RDoc::NormalModule for +raw_name+
+
   def find_class(raw_name, name)
     unless @classes[raw_name]
       if raw_name =~ /^rb_m/
@@ -510,7 +534,7 @@ def find_const_comment(type, const_name)
   #      ARGF.readlines(sep=$/)     -> array
   #      ARGF.readlines(limit)      -> array
   #      ARGF.readlines(sep, limit) -> array
-  #   
+  #
   #      ARGF.to_a(sep=$/)     -> array
   #      ARGF.to_a(limit)      -> array
   #      ARGF.to_a(sep, limit) -> array
@@ -557,6 +581,9 @@ def find_modifiers comment, meth_obj
     end
   end
 
+  ##
+  # Finds a <tt>Document-method</tt> override for +meth_name+ in +class_name+
+
   def find_override_comment(class_name, meth_name)
     name = Regexp.escape(meth_name)
 
@@ -567,6 +594,10 @@ def find_override_comment(class_name, meth_name)
     end
   end
 
+  ##
+  # Creates a new RDoc::Attr +attr_name+ on class +var_name+ that is either
+  # +read+, +write+ or both
+
   def handle_attr(var_name, attr_name, read, write)
     rw = ''
     rw << 'R' if '1' == read
@@ -588,9 +619,13 @@ def handle_attr(var_name, attr_name, read, write)
     attr = RDoc::Attr.new '', name, rw, comment
 
     class_obj.add_attribute attr
-    @stats.add_method attr
+    @stats.add_attribute attr
   end
 
+  ##
+  # Creates a new RDoc::NormalClass or RDoc::NormalModule based on +type+
+  # named +class_name+ in +parent+ which was assigned to the C +var_name+.
+
   def handle_class_module(var_name, type, class_name, parent, in_module)
     parent_name = @known_classes[parent] || parent
 
@@ -640,15 +675,14 @@ def handle_class_module(var_name, type, class_name, parent, in_module)
   end
 
   ##
-  # Adds constant comments.  By providing some_value: at the start ofthe
-  # comment you can override the C value of the comment to give a friendly
-  # definition.
+  # Adds constants.  By providing some_value: at the start of the comment you
+  # can override the C value of the comment to give a friendly definition.
   #
   #   /* 300: The perfect score in bowling */
   #   rb_define_const(cFoo, "PERFECT", INT2FIX(300);
   #
-  # Will override +INT2FIX(300)+ with the value +300+ in the output RDoc.
-  # Values may include quotes and escaped colons (\:).
+  # Will override <tt>INT2FIX(300)</tt> with the value +300+ in the output
+  # RDoc.  Values may include quotes and escaped colons (\:).
 
   def handle_constants(type, var_name, const_name, definition)
     class_name = @known_classes[var_name]
@@ -709,6 +743,11 @@ def handle_ifdefs_in(body)
     body.gsub(/^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m, '\1')
   end
 
+  ##
+  # Adds an RDoc::AnyMethod +meth_name+ defined on a class or module assigned
+  # to +var_name+.  +type+ is the type of method definition function used.
+  # +singleton_method+ and +module_function+ create a singleton method.
+
   def handle_method(type, var_name, meth_name, meth_body, param_count,
                     source_file = nil)
     singleton = false
@@ -765,19 +804,27 @@ def handle_method(type, var_name, meth_name, meth_body, param_count,
     end
   end
 
+  ##
+  # Registers a singleton class +sclass_var+ as a singleton of +class_var+
+
   def handle_singleton sclass_var, class_var
     class_name = @known_classes[class_var]
 
     @singleton_classes[sclass_var] = class_name
   end
 
+  ##
+  # Normalizes tabs in +body+
+
   def handle_tab_width(body)
     if /\t/ =~ body
       tab_width = @options.tab_width
       body.split(/\n/).map do |line|
-        1 while line.gsub!(/\t+/) { ' ' * (tab_width*$&.length - $`.length % tab_width)}  && $~ #`
+        1 while line.gsub!(/\t+/) do
+          ' ' * (tab_width * $&.length - $`.length % tab_width)
+        end && $~
         line
-      end .join("\n")
+      end.join "\n"
     else
       body
     end
@@ -808,6 +855,7 @@ def look_for_directives_in(context, comment)
 
     comment
   end
+
   ##
   # Removes lines that are commented out that might otherwise get picked up
   # when scanning for classes and methods
@@ -816,14 +864,17 @@ def remove_commented_out_lines
     @content.gsub!(%r%//.*rb_define_%, '//')
   end
 
+  ##
+  # Removes private comments from +comment+
+
   def remove_private_comments(comment)
     comment.gsub!(/\/?\*--\n(.*?)\/?\*\+\+/m, '')
     comment.sub!(/\/?\*--\n.*/m, '')
   end
 
   ##
-  # Extract the classes/modules and methods from a C file and return the
-  # corresponding top-level object
+  # Extracts the classes, modules, methods, attributes, constants and aliases
+  # from a C file and returns an RDoc::TopLevel for this file
 
   def scan
     remove_commented_out_lines