From 80d6bf2291380b5860b2fa588404d7721bf34c30 Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Fri, 26 Aug 2011 23:45:41 +0000
Subject: * lib/rdoc:  Import RDoc 3.9.4.  Typo and grammar fixes by Luke
 Gruber.   [Ruby 1.9 - Bug #5203]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@33088 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 lib/rdoc/parser.rb | 21 ++++++++++-----------
 1 file changed, 10 insertions(+), 11 deletions(-)

(limited to 'lib/rdoc/parser.rb')

diff --git a/lib/rdoc/parser.rb b/lib/rdoc/parser.rb
index ba7b858595..27267f3d81 100644
--- a/lib/rdoc/parser.rb
+++ b/lib/rdoc/parser.rb
@@ -4,9 +4,9 @@ require 'rdoc/markup/pre_process'
 require 'rdoc/stats'
 
 ##
-# A parser is simple a class that implements
+# A parser is a class that subclasses RDoc::Parser and implements
 #
-#   #initialize(file_name, body, options)
+#   #initialize top_level, file_name, body, options, stats
 #
 # and
 #
@@ -16,17 +16,16 @@ require 'rdoc/stats'
 # and an RDoc::Options object. The scan method is then called to return an
 # appropriately parsed TopLevel code object.
 #
-# The ParseFactory is used to redirect to the correct parser given a
-# filename extension. This magic works because individual parsers have to
-# register themselves with us as they are loaded in. The do this using the
-# following incantation
+# RDoc::Parser::for is a factory that creates the correct parser for a
+# given filename extension.  Parsers have to register themselves RDoc::Parser
+# using parse_files_matching as when they are loaded:
 #
 #   require "rdoc/parser"
 #
 #   class RDoc::Parser::Xyz < RDoc::Parser
 #     parse_files_matching /\.xyz$/ # <<<<
 #
-#     def initialize(file_name, body, options)
+#     def initialize top_level, file_name, body, options, stats
 #       ...
 #     end
 #
@@ -35,8 +34,8 @@ require 'rdoc/stats'
 #     end
 #   end
 #
-# Just to make life interesting, if we suspect a plain text file, we also
-# look for a shebang line just in case it's a potential shell script
+# If a plain text file is detected, RDoc also looks for a shebang line in case
+# the file is a shell script.
 
 class RDoc::Parser
 
@@ -45,8 +44,8 @@ class RDoc::Parser
   class << self
 
     ##
-    # A Hash that maps file extensions regular expressions to parsers that
-    # will consume them.
+    # An Array of arrays that maps file extension (or name) regular
+    # expressions to parser classes that will parse matching filenames.
     #
     # Use parse_files_matching to register a parser's file extensions.
 
-- 
cgit v1.2.3