Update documentation

Author: drbrain

TODO.rdoc

@@ -3,6 +3,7 @@ Some file contains some things that might happen in RDoc, or might not
 === RDoc 3.10
 
 * Copy static files into doc dir for HTML
+* Add sections to the ToC
 
 === RDoc 3.11
 
@@ -11,6 +12,7 @@ Some file contains some things that might happen in RDoc, or might not
   * Parse only changed files (like in ruby)
 * Page of Glory (or Shame) in HTML output showing documentation coverage
   statistics.
+* Link to the parent-class implementation of methods that use super
 
 === RDoc 4
 

lib/rdoc/cross_reference.rb

@@ -91,6 +91,9 @@ class RDoc::CrossReference
                       # labels for headings
                       (?:@[\w+%-]+)?/x
 
+  ##
+  # Hash of references that have been looked-up to their replacements
+
   attr_accessor :seen
 
   ##

lib/rdoc/markup/heading.rb

@@ -6,10 +6,17 @@ class RDoc::Markup::Heading < Struct.new :level, :text
   @to_html = nil
   @to_label = nil
 
+  ##
+  # A singleton RDoc::Markup::ToLabel formatter for headings.
+
   def self.to_label
     @to_label ||= RDoc::Markup::ToLabel.new
   end
 
+  ##
+  # A singleton plain HTML formatter for headings.  Used for creating labels
+  # for the Table of Contents
+
   def self.to_html
     return @to_html if @to_html
 

lib/rdoc/markup/pre_process.rb

@@ -10,6 +10,10 @@
 
 class RDoc::Markup::PreProcess
 
+  ##
+  # An RDoc::Options instance that will be filled in with overrides from
+  # directives
+
   attr_accessor :options
 
   ##
@@ -75,8 +79,9 @@ def initialize(input_file_name, include_path)
   # If no matching directive was registered the directive is restored to the
   # text.
   #
-  # If +code_object+ is given and the param is set as metadata on the
-  # +code_object+.  See RDoc::CodeObject#metadata
+  # If +code_object+ is given and the directive is unknown then the
+  # directive's parameter is set as metadata on the +code_object+.  See
+  # RDoc::CodeObject#metadata for details.
 
   def handle text, code_object = nil, &block
     if RDoc::Comment === text then
@@ -116,6 +121,14 @@ def handle text, code_object = nil, &block
     text
   end
 
+  ##
+  # Performs the actions described by +directive+ and its parameter +param+.
+  #
+  # +code_object+ is used for directives that operate on a class or module.
+  # +prefix+ is used to ensure the replacement for handled directives is
+  # correct.  +encoding+ is used for the <tt>include</tt> directive.
+  #
+  # For a list of directives in RDoc see RDoc::Markup.
   #--
   # When 1.8.7 support is ditched prefix can be defaulted to ''
 

lib/rdoc/markup/to_html_snippet.rb

@@ -121,6 +121,9 @@ def start_accepting
     @characters = 0
   end
 
+  ##
+  # Removes escaping from the cross-references in +special+
+
   def handle_special_CROSSREF special
     special.text.sub(/\A\\/, '')
   end
@@ -226,18 +229,29 @@ def convert_flow flow
     res.join
   end
 
+  ##
+  # Maintains a bitmask to allow HTML elements to be closed properly.  See
+  # RDoc::Markup::Formatter.
+
   def on_tags res, item
     @mask ^= item.turn_on
 
     super
   end
 
+  ##
+  # Maintains a bitmask to allow HTML elements to be closed properly.  See
+  # RDoc::Markup::Formatter.
+
   def off_tags res, item
     @mask ^= item.turn_off
 
     super
   end
 
+  ##
+  # Truncates +text+ at the end of the first word after the character_limit.
+
   def truncate text
     length = text.length
     characters = @characters
@@ -247,7 +261,7 @@ def truncate text
 
     remaining = @character_limit - characters
 
-    text =~ /\A(.{#{remaining},}?)(\s|$)/m
+    text =~ /\A(.{#{remaining},}?)(\s|$)/m # TODO word-break instead of \s?
 
     $1
   end

lib/rdoc/method_attr.rb

@@ -343,6 +343,10 @@ def inspect # :nodoc:
     ]
   end
 
+  ##
+  # Used by RDoc::Generator::JsonIndex to create a record for the search
+  # engine.
+
   def search_record
     [
       @name,
@@ -354,6 +358,7 @@ def search_record
       snippet(@comment),
     ]
   end
+
   def to_s # :nodoc:
     if @is_alias_for
       "#{self.class.name}: #{full_name} -> #{is_alias_for}"

lib/rdoc/parser/rd.rb

@@ -8,6 +8,9 @@ class RDoc::Parser::RD < RDoc::Parser
 
   parse_files_matching(/\.rd(?:\.[^.]+)?$/)
 
+  ##
+  # Creates an rd-format TopLevel for the given file.
+
   def scan
     comment = RDoc::Comment.new @content, @top_level
     comment.format = 'rd'

lib/rdoc/rd/block_parser.ry

@@ -228,6 +228,8 @@ end
 
 ---- inner
 
+# :stopdoc:
+
 TMPFILE = ["rdtmp", $$, 0]
 
 MARK_TO_LEVEL = {
@@ -239,10 +241,27 @@ MARK_TO_LEVEL = {
   '++'   => 6,
 }
 
+# :startdoc:
+
+##
+# Footnotes for this document
+
 attr_reader :footnotes
+
+##
+# Labels for items in this document
+
 attr_reader :labels
+
+##
+# Path to find included files in
+
 attr_accessor :include_path
 
+##
+# Creates a new RDoc::RD::BlockParser.  Use #parse to parse an rd-format
+# document.
+
 def initialize
   @inline_parser = RDoc::RD::InlineParser.new self
   @include_path = []
@@ -252,6 +271,9 @@ def initialize
   @labels    = {}
 end
 
+##
+# Parses +src+ and returns an RDoc::Markup::Document.
+
 def parse src
   @src = src
   @src.push false
@@ -293,7 +315,10 @@ def parse src
   document
 end
 
-def next_token
+##
+# Returns the next token from the document
+
+def next_token # :nodoc:
   # preprocessing
   # if it is not in RD part
   # => method
@@ -445,12 +470,10 @@ def next_token
   end
 end
 
-=begin private
-  --- RDParser#if_current_indent_equal(indent)
-        if (({@current_indent == ((|indent|))})) then yield block, otherwise
-        process indentation.
-=end
-# always @current_indent = @indent_stack.join("")
+##
+# Yields to the given block if +indent+ matches the current indent, otherwise
+# an indentation token is processed.
+
 def if_current_indent_equal(indent)
   indent = indent.sub(/\t/, "\s" * 8)
   if @current_indent == indent
@@ -466,6 +489,9 @@ def if_current_indent_equal(indent)
 end
 private :if_current_indent_equal
 
+##
+# Cuts off excess whitespace in +src+
+
 def cut_off(src)
   ret = []
   whiteline_buf = []
@@ -499,6 +525,9 @@ def set_term_to_element(parent, term)
 end
 private :set_term_to_element
 
+##
+# Raises a ParseError
+
 def on_error(et, ev, _values)
   prv, cur, nxt = format_line_num(@i, @i+1, @i+2)
 
@@ -512,17 +541,26 @@ RD syntax error: line #{@i+1}:
 Msg
 end
 
+##
+# Current line number
+
 def line_index
   @i
 end
 
+##
+# Parses subtree +src+
+
 def parse_subtree src
   @subparser ||= RDoc::RD::BlockParser.new
 
   @subparser.parse src
 end
 private :parse_subtree
 
+##
+# Retrieves the content for +file+ from the include_path
+
 def get_included(file)
   included = []
 
@@ -539,23 +577,35 @@ def get_included(file)
 end
 private :get_included
 
-def format_line_num(*args)
-  width = args.collect{|i| i.to_s.length }.max
-  args.collect{|i| sprintf("%#{width}d", i) }
+##
+# Formats line numbers +line_numbers+ prettily
+
+def format_line_num(*line_numbers)
+  width = line_numbers.collect{|i| i.to_s.length }.max
+  line_numbers.collect{|i| sprintf("%#{width}d", i) }
 end
 private :format_line_num
 
+##
+# Retrieves the content of +values+ as a single String
+
 def content values
  values.map { |value| value.content }.join
 end
 
+##
+# Creates a paragraph for +value+
+
 def paragraph value
   content = cut_off(value).join(' ').rstrip
   contents = @inline_parser.parse content
 
   RDoc::Markup::Paragraph.new(*contents)
 end
 
+##
+# Adds footnote +content+ to the document
+
 def add_footnote content
   index = @footnotes.length + 1
 
@@ -566,6 +616,9 @@ def add_footnote content
   index
 end
 
+##
+# Adds label +label+ to the document
+
 def add_label label
   @labels[label] = true
 

lib/rdoc/rd/inline_parser.ry

@@ -355,6 +355,9 @@ class InlineParser
 end
 
 ---- inner
+
+# :stopdoc:
+
 EM_OPEN = '((*'
 EM_OPEN_RE = /\A#{Regexp.quote(EM_OPEN)}/
 EM_CLOSE = '*))'
@@ -417,6 +420,8 @@ OTHER_RE = Regexp.new(
               #{Regexp.quote(BACK_SLASH)}|
               #{Regexp.quote(URL)})", other_re_mode)
 
+# :startdoc:
+
 def initialize block_parser
   @block_parser = block_parser
 end

lib/rdoc/test_case.rb

@@ -40,6 +40,10 @@ def setup
     @pwd = Dir.pwd
   end
 
+  ##
+  # Creates an RDoc::Comment with +text+ which was defined on +top_level+.
+  # By default the comment has the 'rdoc' format.
+
   def comment text, top_level = @top_level
     RDoc::Comment.new text, top_level
   end