Apply typo and grammar fixes by Luke Gruber. From [Ruby 1.9 - Bug #5203]

Author: drbrain

lib/rdoc/markup.rb

@@ -36,7 +36,7 @@
 # sequences, and to add special processing for text that matches a
 # regular expression.  Here we make WikiWords significant to the parser,
 # and also make the sequences {word} and \<no>text...</no> signify
-# strike-through text.  When then subclass the HTML output class to deal
+# strike-through text.  We then subclass the HTML output class to deal
 # with these:
 #
 #   require 'rdoc/markup'
@@ -61,7 +61,7 @@
 #
 # == Encoding
 #
-# Where Encoding support is available RDoc will automatically convert all
+# Where Encoding support is available, RDoc will automatically convert all
 # documents to the same output encoding.  The output encoding can be set via
 # RDoc::Options#encoding and defaults to Encoding.default_external.
 #
@@ -127,7 +127,7 @@
 # === Simple Lists
 #
 # If a paragraph starts with a "*", "-", "<digit>." or "<letter>.",
-# then it is taken to be the start of a list.  The margin in increased to be
+# then it is taken to be the start of a list.  The margin is increased to be
 # the first non-space following the list start flag.  Subsequent lines
 # should be indented to this new margin until the list ends.  For example:
 #
@@ -444,10 +444,10 @@
 #
 # [+:nodoc:+ / <tt>:nodoc: all</tt>]
 #   This directive prevents documentation for the element from
-#   being generated.  For classes and modules, the methods, aliases,
+#   being generated.  For classes and modules, methods, aliases,
 #   constants, and attributes directly within the affected class or
 #   module also will be omitted.  By default, though, modules and
-#   classes within that class of module _will_ be documented.  This is
+#   classes within that class or module _will_ be documented.  This is
 #   turned off by adding the +all+ modifier.
 #
 #     module MyModule # :nodoc:
@@ -591,7 +591,7 @@ class RDoc::Markup
   attr_reader :attribute_manager
 
   ##
-  # Take a block of text and use various heuristics to determine it's
+  # Take a block of text and use various heuristics to determine its
   # structure (paragraphs, lists, and so on).  Invoke an event handler as we
   # identify significant chunks.
 

lib/rdoc/parser.rb

@@ -4,9 +4,9 @@
 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 @@
 # 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 @@
 #     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.