* lib/rdoc/markup/to_joined_paragraph.rb: Completed documentation

* lib/rdoc/parser/c.rb:  ditto
* lib/rdoc/parser/changelog.rb:  ditto
* lib/rdoc/servlet.rb:  ditto
* lib/rdoc/store.rb:  ditto

* lib/rdoc/store.rb:  Improved HTML error page.  Completed
  documentation

* lib/rdoc/parser/ruby.rb:  Fixed bug attaching a comment to A::B = 42
* test/rdoc/test_rdoc_parser_ruby.rb:  Test for above

* test/rdoc/test_rdoc_comment.rb:  Removed garbage


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38256 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

3 files changed, 102 insertions, 7 deletions

diff --git a/lib/rdoc/parser/c.rb b/lib/rdoc/parser/c.rb
index 31be27169c..d371ed0e6a 100644
--- a/lib/rdoc/parser/c.rb
+++ b/lib/rdoc/parser/c.rb
@@ -446,6 +446,10 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  ##
+  # Creates classes and module that were missing were defined due to the file
+  # order being different than the declaration order.
+
   def do_missing
     return if @missing_dependencies.empty?
 
diff --git a/lib/rdoc/parser/changelog.rb b/lib/rdoc/parser/changelog.rb
index 6a21506a93..fd7114daee 100644
--- a/lib/rdoc/parser/changelog.rb
+++ b/lib/rdoc/parser/changelog.rb
@@ -1,11 +1,28 @@
 require 'time'
 
+##
+# A ChangeLog file parser.
+#
+# This parser converts a ChangeLog into an RDoc::Markup::Document.  When
+# viewed as HTML a ChangeLog page will have an entry for each day's entries in
+# the sidebar table of contents.
+#
+# This parser is meant to parse the MRI ChangeLog, but can be used to parse any
+# {GNU style Change
+# Log}[http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html].
+
 class RDoc::Parser::ChangeLog < RDoc::Parser
 
   include RDoc::Parser::Text
 
   parse_files_matching(/(\/|\\|\A)ChangeLog[^\/\\]*\z/)
 
+  ##
+  # Attaches the +continuation+ of the previous line to the +entry_body+.
+  #
+  # Continued function listings are joined together as a single entry.
+  # Continued descriptions are joined to make a single paragraph.
+
   def continue_entry_body entry_body, continuation
     return unless last = entry_body.last
 
@@ -21,6 +38,9 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     end
   end
 
+  ##
+  # Creates an RDoc::Markup::Document given the +groups+ of ChangeLog entries.
+
   def create_document groups
     doc = RDoc::Markup::Document.new
     doc.omit_headings_below = 2
@@ -39,6 +59,10 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     doc
   end
 
+  ##
+  # Returns a list of ChangeLog entries an RDoc::Markup nodes for the given
+  # +entries+.
+
   def create_entries entries
     out = []
 
@@ -52,6 +76,10 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     out
   end
 
+  ##
+  # Returns an RDoc::Markup::List containing the given +items+ in the
+  # ChangeLog
+
   def create_items items
     list = RDoc::Markup::List.new :NOTE
 
@@ -69,12 +97,30 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     list
   end
 
+  ##
+  # Groups +entries+ by date.
+
   def group_entries entries
-    entries.group_by do |title, body|
+    entries.group_by do |title, _|
       Time.parse(title).strftime "%Y-%m-%d"
     end
   end
 
+  ##
+  # Parses the entries in the ChangeLog.
+  #
+  # Returns an Array of each ChangeLog entry in order of parsing.
+  #
+  # A ChangeLog entry is an Array containing the ChangeLog title (date and
+  # committer) and an Array of ChangeLog items (file and function changed with
+  # description).
+  #
+  # An example result would be:
+  #
+  #    [ 'Tue Dec  4 08:33:46 2012  Eric Hodel  <[email protected]>',
+  #      [ 'README.EXT:  Converted to RDoc format',
+  #        'README.EXT.ja:  ditto']]
+
   def parse_entries
     entries = []
     entry_name = nil
@@ -122,6 +168,9 @@ class RDoc::Parser::ChangeLog < RDoc::Parser
     entries
   end
 
+  ##
+  # Converts the ChangeLog into an RDoc::Markup::Document
+
   def scan
     entries = parse_entries
     grouped_entries = group_entries entries
diff --git a/lib/rdoc/parser/ruby.rb b/lib/rdoc/parser/ruby.rb
index fe461ff389..31e31b5ce9 100644
--- a/lib/rdoc/parser/ruby.rb
+++ b/lib/rdoc/parser/ruby.rb
@@ -240,7 +240,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
   # with :: separated named) and return the ultimate name, the associated
   # container, and the given name (with the ::).
 
-  def get_class_or_module container
+  def get_class_or_module container, ignore_constants = false
     skip_tkspace
     name_t = get_tk
     given_name = ''
@@ -259,9 +259,16 @@ class RDoc::Parser::Ruby < RDoc::Parser
     while TkCOLON2 === peek_tk do
       prev_container = container
       container = container.find_module_named name_t.name
-      container ||= prev_container.add_module RDoc::NormalModule, name_t.name
+      container ||=
+        if ignore_constants then
+          RDoc::Context.new
+        else
+          c = prev_container.add_module RDoc::NormalModule, name_t.name
+          c.ignore unless prev_container.document_children
+          c
+        end
 
-      container.ignore unless prev_container.document_children
+      container.record_location @top_level
 
       get_tk
       skip_tkspace false
@@ -663,9 +670,10 @@ class RDoc::Parser::Ruby < RDoc::Parser
   end
 
   ##
-  # Parses a constant in +context+ with +comment+
+  # Parses a constant in +context+ with +comment+.  If +ignore_constants+ is
+  # true, no found constants will be added to RDoc.
 
-  def parse_constant container, tk, comment
+  def parse_constant container, tk, comment, ignore_constants = false
     offset  = tk.seek
     line_no = tk.line_no
 
@@ -676,6 +684,17 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
     eq_tk = get_tk
 
+    if TkCOLON2 === eq_tk then
+      unget_tk eq_tk
+      unget_tk tk
+
+      container, name_t, = get_class_or_module container, ignore_constants
+
+      name = name_t.name
+
+      eq_tk = get_tk
+    end
+
     unless TkASSIGN === eq_tk then
       unget_tk eq_tk
       return false
@@ -1335,6 +1354,26 @@ class RDoc::Parser::Ruby < RDoc::Parser
   end
 
   ##
+  # Parses a rescue
+
+  def parse_rescue
+    skip_tkspace false
+
+    while tk = get_tk
+      case tk
+      when TkNL, TkSEMICOLON then
+        break
+      when TkCOMMA then
+        skip_tkspace false
+
+        get_tk if TkNL === peek_tk
+      end
+
+      skip_tkspace false
+    end
+  end
+
+  ##
   # The core of the ruby parser.
 
   def parse_statements(container, single = NORMAL, current_method = nil,
@@ -1407,7 +1446,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
         parse_method container, single, tk, comment
 
       when TkCONSTANT then
-        unless parse_constant container, tk, comment then
+        unless parse_constant container, tk, comment, current_method then
           try_parse_comment = true
         end
 
@@ -1441,6 +1480,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
       when TkSUPER then
         current_method.calls_super = true if current_method
 
+      when TkRESCUE then
+        parse_rescue
+
       when TkIDENTIFIER then
         if nest == 1 and current_method.nil? then
           case tk.name