diff --git a/lib/rdoc/generators/chm_generator.rb b/lib/rdoc/generators/chm_generator.rb
index 51eeda8dd1..354a444689 100644
--- a/lib/rdoc/generators/chm_generator.rb
+++ b/lib/rdoc/generators/chm_generator.rb
@@ -6,12 +6,13 @@ module Generators
 
     HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
 
+    ##
     # Standard generator factory
+
     def CHMGenerator.for(options)
       CHMGenerator.new(options)
     end
 
-    
     def initialize(*args)
       super
       @op_name = @options.op_name || "rdoc"
@@ -22,32 +23,35 @@ module Generators
       stat = File.stat(HHC_PATH)
     rescue
       $stderr <<
-	"\n.chm output generation requires that Microsoft's Html Help\n" <<
-	"Workshop is installed. RDoc looks for it in:\n\n    " <<
-	HHC_PATH <<
-	"\n\nYou can download a copy for free from:\n\n" <<
-	"    http://msdn.microsoft.com/library/default.asp?" <<
-	"url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n"
-      
+        "\n.chm output generation requires that Microsoft's Html Help\n" <<
+        "Workshop is installed. RDoc looks for it in:\n\n    " <<
+        HHC_PATH <<
+        "\n\nYou can download a copy for free from:\n\n" <<
+        "    http://msdn.microsoft.com/library/default.asp?" <<
+        "url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp\n\n"
+
       exit 99
     end
 
-    # Generate the html as normal, then wrap it
-    # in a help project
+    ##
+    # Generate the html as normal, then wrap it in a help project
+
     def generate(info)
       super
       @project_name = @op_name + ".hhp"
       create_help_project
     end
 
-    # The project contains the project file, a table of contents
-    # and an index
+    ##
+    # The project contains the project file, a table of contents and an index
+
     def create_help_project
       create_project_file
       create_contents_and_index
       compile_project
     end
 
+    ##
     # The project file links together all the various
     # files that go to make up the help.
 
@@ -56,16 +60,17 @@ module Generators
       values = { "title" => @options.title, "opname" => @op_name }
       files = []
       @files.each do |f|
-	files << { "html_file_name" => f.path }
+        files << { "html_file_name" => f.path }
       end
 
       values['all_html_files'] = files
-      
+
       File.open(@project_name, "w") do |f|
         template.write_html_on(f, values)
       end
     end
 
+    ##
     # The contents is a list of all files and modules.
     # For each we include  as sub-entries the list
     # of methods they contain. As we build the contents
@@ -76,37 +81,39 @@ module Generators
       index    = []
 
       (@files+@classes).sort.each do |entry|
-	content_entry = { "c_name" => entry.name, "ref" => entry.path }
-	index << { "name" => entry.name, "aref" => entry.path }
+        content_entry = { "c_name" => entry.name, "ref" => entry.path }
+        index << { "name" => entry.name, "aref" => entry.path }
 
-	internals = []
+        internals = []
 
-	methods = entry.build_method_summary_list(entry.path)
+        methods = entry.build_method_summary_list(entry.path)
 
-	content_entry["methods"] = methods unless methods.empty?
+        content_entry["methods"] = methods unless methods.empty?
         contents << content_entry
-	index.concat methods
+        index.concat methods
       end
 
       values = { "contents" => contents }
       template = TemplatePage.new(RDoc::Page::CONTENTS)
       File.open("contents.hhc", "w") do |f|
-	template.write_html_on(f, values)
+        template.write_html_on(f, values)
       end
 
       values = { "index" => index }
       template = TemplatePage.new(RDoc::Page::CHM_INDEX)
       File.open("index.hhk", "w") do |f|
-	template.write_html_on(f, values)
-      end      
+        template.write_html_on(f, values)
+      end
     end
 
+    ##
     # Invoke the windows help compiler to compiler the project
+
     def compile_project
       system(HHC_PATH, @project_name)
     end
 
   end
 
-
 end
+
diff --git a/lib/rdoc/generators/html_generator.rb b/lib/rdoc/generators/html_generator.rb
index 4348703c30..1497ed7483 100644
--- a/lib/rdoc/generators/html_generator.rb
+++ b/lib/rdoc/generators/html_generator.rb
@@ -1,39 +1,3 @@
-# We're responsible for generating all the HTML files
-# from the object tree defined in code_objects.rb. We
-# generate:
-#
-# [files]   an html file for each input file given. These
-#           input files appear as objects of class
-#           TopLevel
-#
-# [classes] an html file for each class or module encountered.
-#           These classes are not grouped by file: if a file
-#           contains four classes, we'll generate an html
-#           file for the file itself, and four html files 
-#           for the individual classes. 
-#
-# [indices] we generate three indices for files, classes,
-#           and methods. These are displayed in a browser
-#           like window with three index panes across the
-#           top and the selected description below
-#
-# Method descriptions appear in whatever entity (file, class,
-# or module) that contains them.
-#
-# We generate files in a structure below a specified subdirectory,
-# normally +doc+.
-#
-#  opdir
-#     |
-#     |___ files
-#     |       |__  per file summaries
-#     |
-#     |___ classes
-#             |__ per class/module descriptions
-#
-# HTML is generated using the Template class.
-#
-
 require 'fileutils'
 
 require 'rdoc/options'
@@ -44,24 +8,32 @@ require 'cgi'
 
 module Generators
 
-  # Name of sub-direcories that hold file and class/module descriptions
+  ##
+  # Name of sub-direcory that holds file descriptions
 
   FILE_DIR  = "files"
+
+  ##
+  # Name of sub-direcory that holds class descriptions
+
   CLASS_DIR = "classes"
+
+  ##
+  # Name of the RDoc CSS file
+
   CSS_NAME  = "rdoc-style.css"
-  
 
   ##
   # Build a hash of all items that can be cross-referenced.
-  # This is used when we output required and included names: 
+  # This is used when we output required and included names:
   # if the names appear in this hash, we can generate
   # an html cross reference to the appropriate description.
-  # We also use this when parsing comment blocks: any decorated 
+  # We also use this when parsing comment blocks: any decorated
   # words matching an entry in this list are hyperlinked.
 
   class AllReferences
     @@refs = {}
-    
+
     def AllReferences::reset
       @@refs = {}
     end
@@ -79,7 +51,6 @@ module Generators
     end
   end
 
-
   ##
   # Subclass of the SM::ToHtml class that supports looking
   # up words in the AllReferences list. Those that are
@@ -87,6 +58,8 @@ module Generators
   # be hyperlinked
 
   class HyperlinkHtml < SM::ToHtml
+
+    ##
     # We need to record the html path of our caller so we can generate
     # correct relative paths for any hyperlinks that we find
     def initialize(from_path, context)
@@ -98,6 +71,7 @@ module Generators
       @context = context
     end
 
+    ##
     # We're invoked when any text matches the CROSSREF pattern
     # (defined in MarkUp). If we fine the corresponding reference,
     # generate a hyperlink. If the name we're looking for contains
@@ -134,9 +108,10 @@ module Generators
       end
     end
 
-
+    ##
     # Generate a hyperlink for url, labeled with text. Handle the
     # special cases for img: and link: described under handle_special_HYPEDLINK
+
     def gen_url(url, text)
       if url =~ /([A-Za-z]+):(.*)/
         type = $1
@@ -155,7 +130,7 @@ module Generators
         end
       end
 
-      if (type == "http" || type == "link") && 
+      if (type == "http" || type == "link") &&
           url =~ /\.(gif|png|jpg|jpeg|bmp)$/
 
         "<img src=\"#{url}\" />"
@@ -164,6 +139,7 @@ module Generators
       end
     end
 
+    ##
     # And we're invoked with a potential external hyperlink mailto:
     # just gets inserted. http: links are checked to see if they
     # reference an image. If so, that image gets inserted using an
@@ -176,14 +152,14 @@ module Generators
       gen_url(url, url)
     end
 
-    # HEre's a hypedlink where the label is different to the URL
+    ##
+    # Here's a hypedlink where the label is different to the URL
     #  <label>[url]
-    #
-    
+
     def handle_special_TIDYLINK(special)
       text = special.text
 #      unless text =~ /(\S+)\[(.*?)\]/
-      unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/ 
+      unless text =~ /\{(.*?)\}\[(.*?)\]/ or text =~ /(\S+)\[(.*?)\]/
         return text
       end
       label = $1
@@ -193,15 +169,12 @@ module Generators
 
   end
 
-
-  
-  #####################################################################
-  #
+  ##
   # Handle common markup tasks for the various Html classes
-  #
 
   module MarkUp
 
+    ##
     # Convert a string in markup format into HTML. We keep a cached
     # SimpleMarkup object lying around after the first time we're
     # called per object.
@@ -217,9 +190,9 @@ module Generators
                              | \#\w+(\([.\w\*\/\+\-\=\<\>]+\))?  #  meth(**) (for operator in Fortran95)
                              | \b([A-Z]\w*(::\w+)*[.\#]\w+)  #    A::B.meth
                              | \b([A-Z]\w+(::\w+)*)       #    A::B..
-                             | \#\w+[!?=]?                #    #meth_name 
+                             | \#\w+[!?=]?                #    #meth_name
                              | \b\w+([_\/\.]+\w+)*[!?=]?  #    meth_name
-                             )/x, 
+                             )/x,
                             :CROSSREF)
 
         # external hyperlinks
@@ -251,6 +224,7 @@ module Generators
       res
     end
 
+    ##
     # Qualify a stylesheet URL; if if +css_name+ does not begin with '/' or
     # 'http[s]://', prepend a prefix relative to +path+. Otherwise, return it
     # unmodified.
@@ -265,6 +239,7 @@ module Generators
       end
     end
 
+    ##
     # Build a webcvs URL with the given 'url' argument. URLs with a '%s' in them
     # get the file's path sprintfed into them; otherwise they're just catenated
     # together.
@@ -276,34 +251,35 @@ module Generators
         return url + full_path
       end
     end
+
   end
 
-
-  #####################################################################
-  #
+  ##
   # A Context is built by the parser to represent a container: contexts
   # hold classes, modules, methods, require lists and include lists.
   # ClassModule and TopLevel are the context objects we process here
-  # 
+
   class ContextUser
 
     include MarkUp
 
     attr_reader :context
-    
+
     def initialize(context, options)
       @context = context
       @options = options
     end
-      
+
+    ##
     # convenience method to build a hyperlink
+
     def href(link, cls, name)
       %{<a href="#{link}" class="#{cls}">#{name}</a>} #"
     end
 
-    # return a reference to outselves to be used as an href=
-    # the form depends on whether we're all in one file
-    # or in multiple files
+    ##
+    # Returns a reference to outselves to be used as an href= the form depends
+    # on whether we're all in one file or in multiple files
 
     def as_href(from_path)
       if @options.all_one_file
@@ -313,10 +289,11 @@ module Generators
       end
     end
 
-    # Create a list of HtmlMethod objects for each method
-    # in the corresponding context object. If the @options.show_all
-    # variable is set (corresponding to the <tt>--all</tt> option,
-    # we include all methods, otherwise just the public ones.
+    ##
+    # Create a list of HtmlMethod objects for each method in the corresponding
+    # context object. If the @options.show_all variable is set (corresponding
+    # to the <tt>--all</tt> option, we include all methods, otherwise just the
+    # public ones.
 
     def collect_methods
       list = @context.method_list
@@ -326,23 +303,26 @@ module Generators
       @methods = list.collect {|m| HtmlMethod.new(m, self, @options) }
     end
 
+    ##
     # Build a summary list of all the methods in this context
+
     def build_method_summary_list(path_prefix="")
       collect_methods unless @methods
       meths = @methods.sort
       res = []
       meths.each do |meth|
-	res << {
+        res << {
           "name" => CGI.escapeHTML(meth.name),
-          "aref" => "#{path_prefix}\##{meth.aref}" 
+          "aref" => "#{path_prefix}\##{meth.aref}"
         }
       end
       res
     end
 
-
+    ##
     # Build a list of aliases for which we couldn't find a
     # corresponding method
+
     def build_alias_summary_list(section)
       values = []
       @context.aliases.each do |al|
@@ -358,8 +338,10 @@ module Generators
       end
       values
     end
-    
+
+    ##
     # Build a list of constants
+
     def build_constants_summary_list(section)
       values = []
       @context.constants.each do |co|
@@ -373,7 +355,7 @@ module Generators
       end
       values
     end
-    
+
     def build_requires_list(context)
       potentially_referenced_list(context.requires) {|fn| [fn + ".rb"] }
     end
@@ -382,6 +364,7 @@ module Generators
       potentially_referenced_list(context.includes)
     end
 
+    ##
     # Build a list from an array of <i>Htmlxxx</i> items. Look up each
     # in the AllReferences hash: if we find a corresponding entry,
     # we generate a hyperlink to it, otherwise just output the name.
@@ -394,12 +377,12 @@ module Generators
     def potentially_referenced_list(array)
       res = []
       array.each do |i|
-        ref = AllReferences[i.name] 
+        ref = AllReferences[i.name]
 #         if !ref
 #           container = @context.parent
 #           while !ref && container
 #             name = container.name + "::" + i.name
-#             ref = AllReferences[name] 
+#             ref = AllReferences[name]
 #             container = container.parent
 #           end
 #         end
@@ -424,6 +407,7 @@ module Generators
       res
     end
 
+    ##
     # Build an array of arrays of method details. The outer array has up
     # to six entries, public, private, and protected for both class
     # methods, the other for instance methods. The inner arrays contain
@@ -434,12 +418,12 @@ module Generators
 
       methods = @methods.sort
       for singleton in [true, false]
-        for vis in [ :public, :protected, :private ] 
+        for vis in [ :public, :protected, :private ]
           res = []
           methods.each do |m|
             if m.section == section and
-                m.document_self and 
-                m.visibility == vis and 
+                m.document_self and
+                m.visibility == vis and
                 m.singleton == singleton
               row = {}
               if m.call_seq
@@ -459,7 +443,7 @@ module Generators
                   alias_names << {
                     'name' => other.name,
                     'aref'  => other.viewer.as_href(path)
-                  } 
+                  }
                 end
               end
               unless alias_names.empty?
@@ -479,7 +463,7 @@ module Generators
               res << row
             end
           end
-          if res.size > 0 
+          if res.size > 0
             outer << {
               "type"    => vis.to_s.capitalize,
               "category"    => singleton ? "Class" : "Instance",
@@ -491,8 +475,9 @@ module Generators
       outer
     end
 
+    ##
     # Build the structured list of classes and modules contained
-    # in this context. 
+    # in this context.
 
     def build_class_list(level, from, section, infile=nil)
       res = ""
@@ -502,7 +487,7 @@ module Generators
         next unless mod.section == section
         next if infile && !mod.defined_in?(infile)
         if mod.document_self
-          res << 
+          res <<
             prefix <<
             "Module " <<
             href(url(mod.viewer.path), "link", mod.full_name) <<
@@ -516,7 +501,7 @@ module Generators
         next if infile && !cls.defined_in?(infile)
         if cls.document_self
           res      <<
-            prefix << 
+            prefix <<
             "Class " <<
             href(url(cls.viewer.path), "link", cls.full_name) <<
             "<br />\n" <<
@@ -526,7 +511,7 @@ module Generators
 
       res
     end
-    
+
     def url(target)
       HTMLGenerator.gen_url(path, target)
     end
@@ -550,8 +535,9 @@ module Generators
       res
     end
 
-
+    ##
     # Find a symbol in ourselves or our parent
+
     def find_symbol(symbol, method=nil)
       res = @context.find_symbol(symbol, method)
       if res
@@ -560,8 +546,9 @@ module Generators
       res
     end
 
+    ##
     # create table of contents if we contain sections
-      
+
     def add_table_of_sections
       toc = []
       @context.sections.each do |section|
@@ -572,15 +559,13 @@ module Generators
           }
         end
       end
-      
+
       @values['toc'] = toc unless toc.empty?
     end
 
-
   end
 
-  #####################################################################
-  #
+  ##
   # Wrap a ClassModule context
 
   class HtmlClass < ContextUser
@@ -607,8 +592,10 @@ module Generators
       AllReferences.add(name, self)
     end
 
-    # return the relative file name to store this class in,
-    # which is also its url
+    ##
+    # Returns the relative file name to store this class in, which is also its
+    # url
+
     def http_url(full_name, prefix)
       path = full_name.dup
       if path['<<']
@@ -617,7 +604,6 @@ module Generators
       File.join(prefix, path.split("::")) + ".html"
     end
 
-
     def name
       @context.full_name
     end
@@ -664,16 +650,16 @@ module Generators
 
         al = build_alias_summary_list(section)
         secdata["aliases"] = al unless al.empty?
-        
+
         co = build_constants_summary_list(section)
         secdata["constants"] = co unless co.empty?
-        
+
         al = build_attribute_list(section)
         secdata["attributes"] = al unless al.empty?
-        
+
         cl = build_class_list(0, @context, section)
         secdata["classlist"] = cl unless cl.empty?
-        
+
         mdl = build_method_detail_list(section)
         secdata["method_list"] = mdl unless mdl.empty?
 
@@ -690,8 +676,8 @@ module Generators
         next unless att.section == section
         if att.visibility == :public || att.visibility == :protected || @options.show_all
           entry = {
-            "name"   => CGI.escapeHTML(att.name), 
-            "rw"     => att.rw, 
+            "name"   => CGI.escapeHTML(att.name),
+            "rw"     => att.rw,
             "a_desc" => markup(att.comment, true)
           }
           unless att.visibility == :public || att.visibility == :protected
@@ -720,19 +706,19 @@ module Generators
       parent_class = @context.superclass
 
       if parent_class
-	@values["parent"] = CGI.escapeHTML(parent_class)
+        @values["parent"] = CGI.escapeHTML(parent_class)
 
-	if parent_name
-	  lookup = parent_name + "::" + parent_class
-	else
-	  lookup = parent_class
-	end
+        if parent_name
+          lookup = parent_name + "::" + parent_class
+        else
+          lookup = parent_class
+        end
 
-	parent_url = AllReferences[lookup] || AllReferences[parent_class]
+        parent_url = AllReferences[lookup] || AllReferences[parent_class]
 
-	if parent_url and parent_url.document_self
-	  @values["par_url"] = aref_to(parent_url.path)
-	end
+        if parent_url and parent_url.document_self
+          @values["par_url"] = aref_to(parent_url.path)
+        end
       end
 
       files = []
@@ -759,8 +745,7 @@ module Generators
 
   end
 
-  #####################################################################
-  #
+  ##
   # Handles the mapping of a file's information to HTML. In reality,
   # a file corresponds to a +TopLevel+ object, containing modules,
   # classes, and top-level methods. In theory it _could_ contain
@@ -851,16 +836,16 @@ module Generators
 
         al = build_alias_summary_list(section)
         secdata["aliases"] = al unless al.empty?
-        
+
         co = build_constants_summary_list(section)
         @values["constants"] = co unless co.empty?
 
         secdata
       end
-      
+
       @values
     end
-    
+
     def write_on(f)
       value_hash
       template = TemplatePage.new(RDoc::Page::BODY,
@@ -872,7 +857,7 @@ module Generators
     def file_attribute_values
       full_path = @context.file_absolute_name
       short_name = File.basename(full_path)
-      
+
       @values["title"] = CGI.escapeHTML("File: #{short_name}")
 
       if @context.diagram
@@ -891,11 +876,13 @@ module Generators
     def <=>(other)
       self.name <=> other.name
     end
+
   end
 
-  #####################################################################
+  ##
 
   class HtmlMethod
+
     include MarkUp
 
     attr_reader :context
@@ -931,10 +918,10 @@ module Generators
 
       AllReferences.add(name, self)
     end
-    
-    # return a reference to outselves to be used as an href=
-    # the form depends on whether we're all in one file
-    # or in multiple files
+
+    ##
+    # Returns a reference to outselves to be used as an href= the form depends
+    # on whether we're all in one file or in multiple files
 
     def as_href(from_path)
       if @options.all_one_file
@@ -970,9 +957,9 @@ module Generators
 
     def path
       if @options.all_one_file
-	aref
+        aref
       else
-	@html_class.path + "#" + aref
+        @html_class.path + "#" + aref
       end
     end
 
@@ -1005,7 +992,7 @@ module Generators
         p = @context.params.gsub(/\s*\#.*/, '')
         p = p.tr("\n", " ").squeeze(" ")
         p = "(" + p + ")" unless p[0] == ?(
-        
+
         if (block = @context.block_params)
          # If this method has explicit block parameters, remove any
          # explicit &block
@@ -1022,7 +1009,7 @@ module Generators
       end
       CGI.escapeHTML(p)
     end
-    
+
     def create_source_code_file(code_body)
       meth_path = @html_class.path.sub(/\.html$/, '.src')
       FileUtils.mkdir_p(meth_path)
@@ -1053,7 +1040,6 @@ module Generators
     # Given a sequence of source tokens, mark up the source code
     # to make it look purty.
 
-
     def markup_code(tokens)
       src = ""
       tokens.each do |t|
@@ -1088,8 +1074,8 @@ module Generators
       src
     end
 
-    # we rely on the fact that the first line of a source code
-    # listing has 
+    ##
+    # We rely on the fact that the first line of a source code listing has
     #    # File xxxxx, line dddd
 
     def add_line_numbers(src)
@@ -1100,7 +1086,7 @@ module Generators
         real_fmt = "%#{size}d: "
         fmt = " " * (size+2)
         src.gsub!(/^/) do
-          res = sprintf(fmt, first) 
+          res = sprintf(fmt, first)
           first += 1
           fmt = real_fmt
           res
@@ -1123,39 +1109,73 @@ module Generators
       end
       res
     end
+
   end
 
-  #####################################################################
+  ##
+  # We're responsible for generating all the HTML files
+  # from the object tree defined in code_objects.rb. We
+  # generate:
+  #
+  # [files]   an html file for each input file given. These
+  #           input files appear as objects of class
+  #           TopLevel
+  #
+  # [classes] an html file for each class or module encountered.
+  #           These classes are not grouped by file: if a file
+  #           contains four classes, we'll generate an html
+  #           file for the file itself, and four html files
+  #           for the individual classes.
+  #
+  # [indices] we generate three indices for files, classes,
+  #           and methods. These are displayed in a browser
+  #           like window with three index panes across the
+  #           top and the selected description below
+  #
+  # Method descriptions appear in whatever entity (file, class,
+  # or module) that contains them.
+  #
+  # We generate files in a structure below a specified subdirectory,
+  # normally +doc+.
+  #
+  #  opdir
+  #     |
+  #     |___ files
+  #     |       |__  per file summaries
+  #     |
+  #     |___ classes
+  #             |__ per class/module descriptions
+  #
+  # HTML is generated using the Template class.
 
   class HTMLGenerator
 
     include MarkUp
 
     ##
-    # convert a target url to one that is relative to a given
-    # path
-    
+    # Converts a target url to one that is relative to a given path
+
     def HTMLGenerator.gen_url(path, target)
       from          = File.dirname(path)
       to, to_file   = File.split(target)
-      
+
       from = from.split("/")
       to   = to.split("/")
-      
+
       while from.size > 0 and to.size > 0 and from[0] == to[0]
         from.shift
         to.shift
       end
-      
+
       from.fill("..")
       from.concat(to)
       from << to_file
       File.join(*from)
     end
 
-    # Generators may need to return specific subclasses depending
-    # on the options they are passed. Because of this
-    # we create them using a factory
+    ##
+    # Generators may need to return specific subclasses depending on the
+    # options they are passed. Because of this we create them using a factory
 
     def HTMLGenerator.for(options)
       AllReferences::reset
@@ -1172,19 +1192,19 @@ module Generators
       protected :new
     end
 
-    # Set up a new HTML generator. Basically all we do here is load
-    # up the correct output temlate
+    ##
+    # Set up a new HTML generator. Basically all we do here is load up the
+    # correct output temlate
 
     def initialize(options) #:not-new:
       @options    = options
       load_html_template
     end
 
-
     ##
     # Build the initial indices and output objects
     # based on an array of TopLevel objects containing
-    # the extracted information. 
+    # the extracted information.
 
     def generate(toplevels)
       @toplevels  = toplevels
@@ -1202,7 +1222,7 @@ module Generators
     ##
     # Load up the HTML template specified in the options.
     # If the template name contains a slash, use it literally
-    #
+
     def load_html_template
       template = @options.template
       unless template =~ %r{/|\\}
@@ -1218,8 +1238,7 @@ module Generators
 
     ##
     # Write out the style sheet used by the main frames
-    #
-    
+
     def write_style_sheet
       template = TemplatePage.new(RDoc::Page::STYLE)
       unless @options.css
@@ -1231,13 +1250,12 @@ module Generators
     end
 
     ##
-    # See the comments at the top for a description of the
-    # directory structure
+    # See the comments at the top for a description of the directory structure
 
     def gen_sub_directories
       FileUtils.mkdir_p(FILE_DIR)
       FileUtils.mkdir_p(CLASS_DIR)
-    rescue 
+    rescue
       $stderr.puts $!.message
       exit 1
     end
@@ -1271,7 +1289,7 @@ module Generators
 
     ##
     # Generate all the HTML
-    #
+
     def generate_html
       # the individual descriptions for files and classes
       gen_into(@files)
@@ -1281,7 +1299,7 @@ module Generators
       gen_class_index
       gen_method_index
       gen_main_index
-      
+
       # this method is defined in the template file
       write_extra_pages if defined? write_extra_pages
     end
@@ -1298,8 +1316,8 @@ module Generators
     end
 
     def gen_file_index
-      gen_an_index(@files, 'Files', 
-                   RDoc::Page::FILE_INDEX, 
+      gen_an_index(@files, 'Files',
+                   RDoc::Page::FILE_INDEX,
                    "fr_file_index.html")
     end
 
@@ -1310,12 +1328,11 @@ module Generators
     end
 
     def gen_method_index
-      gen_an_index(HtmlMethod.all_methods, 'Methods', 
+      gen_an_index(HtmlMethod.all_methods, 'Methods',
                    RDoc::Page::METHOD_INDEX,
                    "fr_method_index.html")
     end
 
-    
     def gen_an_index(collection, title, template, filename)
       template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
       res = []
@@ -1338,10 +1355,11 @@ module Generators
       end
     end
 
-    # The main index page is mostly a template frameset, but includes
-    # the initial page. If the <tt>--main</tt> option was given,
-    # we use this as our main page, otherwise we use the
-    # first file specified on the command line.
+    ##
+    # The main index page is mostly a template frameset, but includes the
+    # initial page. If the <tt>--main</tt> option was given, we use this as
+    # our main page, otherwise we use the first file specified on the command
+    # line.
 
     def gen_main_index
       template = TemplatePage.new(RDoc::Page::INDEX)
@@ -1358,7 +1376,9 @@ module Generators
       end
     end
 
-    # return the url of the main page
+    ##
+    # Returns the url of the main page
+
     def main_url
       main_page = @options.main_page
       ref = nil
@@ -1374,7 +1394,7 @@ module Generators
       unless ref
         for file in @files
           if file.document_self
-            ref = file.path 
+            ref = file.path
             break
           end
         end
@@ -1389,13 +1409,8 @@ module Generators
       ref
     end
 
-
   end
 
-
-  ######################################################################
-
-
   class HTMLGeneratorInOne < HTMLGenerator
 
     def initialize(*args)
@@ -1405,7 +1420,7 @@ module Generators
     ##
     # Build the initial indices and output objects
     # based on an array of TopLevel objects containing
-    # the extracted information. 
+    # the extracted information.
 
     def generate(info)
       @toplevels  = info
@@ -1417,7 +1432,6 @@ module Generators
       generate_xml
     end
 
-
     ##
     # Generate:
     #
@@ -1448,15 +1462,15 @@ module Generators
     ##
     # Generate all the HTML. For the one-file case, we generate
     # all the information in to one big hash
-    #
+
     def generate_xml
-      values = { 
+      values = {
         'charset' => @options.charset,
         'files'   => gen_into(@files),
         'classes' => gen_into(@classes),
         'title'        => CGI.escapeHTML(@options.title),
       }
-      
+
       # this method is defined in the template file
       write_extra_pages if defined? write_extra_pages
 
@@ -1490,7 +1504,6 @@ module Generators
       gen_an_index(HtmlMethod.all_methods, 'Methods')
     end
 
-    
     def gen_an_index(collection, title)
       res = []
       collection.sort.each do |f|
@@ -1507,4 +1520,6 @@ module Generators
     end
 
   end
+
 end
+
diff --git a/lib/rdoc/generators/ri_generator.rb b/lib/rdoc/generators/ri_generator.rb
index bf22bc8dba..18db389480 100644
--- a/lib/rdoc/generators/ri_generator.rb
+++ b/lib/rdoc/generators/ri_generator.rb
@@ -1,39 +1,3 @@
-# We're responsible for generating all the HTML files
-# from the object tree defined in code_objects.rb. We
-# generate:
-#
-# [files]   an html file for each input file given. These
-#           input files appear as objects of class
-#           TopLevel
-#
-# [classes] an html file for each class or module encountered.
-#           These classes are not grouped by file: if a file
-#           contains four classes, we'll generate an html
-#           file for the file itself, and four html files 
-#           for the individual classes. 
-#
-# [indices] we generate three indices for files, classes,
-#           and methods. These are displayed in a browser
-#           like window with three index panes across the
-#           top and the selected description below
-#
-# Method descriptions appear in whatever entity (file, class,
-# or module) that contains them.
-#
-# We generate files in a structure below a specified subdirectory,
-# normally +doc+.
-#
-#  opdir
-#     |
-#     |___ files
-#     |       |__  per file summaries
-#     |
-#     |___ classes
-#             |__ per class/module descriptions
-#
-# HTML is generated using the Template class.
-#
-
 require 'rdoc/options'
 require 'rdoc/template'
 require 'rdoc/markup/simple_markup'
@@ -47,12 +11,11 @@ require 'rdoc/ri/ri_descriptions'
 
 module Generators
 
-
   class RIGenerator
 
-    # Generators may need to return specific subclasses depending
-    # on the options they are passed. Because of this
-    # we create them using a factory
+    ##
+    # Generators may need to return specific subclasses depending on the
+    # options they are passed. Because of this we create them using a factory
 
     def RIGenerator.for(options)
       new(options)
@@ -62,8 +25,9 @@ module Generators
       protected :new
     end
 
-    # Set up a new HTML generator. Basically all we do here is load
-    # up the correct output temlate
+    ##
+    # Set up a new HTML generator. Basically all we do here is load up the
+    # correct output temlate
 
     def initialize(options) #:not-new:
       @options   = options
@@ -72,11 +36,9 @@ module Generators
       @to_flow   = SM::ToFlow.new
     end
 
-
     ##
-    # Build the initial indices and output objects
-    # based on an array of TopLevel objects containing
-    # the extracted information. 
+    # Build the initial indices and output objects based on an array of
+    # TopLevel objects containing the extracted information.
 
     def generate(toplevels)
       RDoc::TopLevel.all_classes_and_modules.each do |cls|
@@ -163,8 +125,8 @@ module Generators
 
     private
 
-    # return a list of class and instance methods that we'll be
-    # documenting
+    ##
+    # Returns a list of class and instance methods that we'll be documenting
 
     def method_list(cls)
       list = cls.method_list
@@ -185,17 +147,17 @@ module Generators
       end
       return c,i
     end
-    
+
     def params_of(method)
       if method.call_seq
         method.call_seq
       else
         params = method.params || ""
-        
+
         p = params.gsub(/\s*\#.*/, '')
         p = p.tr("\n", " ").squeeze(" ")
         p = "(" + p + ")" unless p[0] == ?(
-        
+
         if (block = method.block_params)
           block.gsub!(/\s*\#.*/, '')
           block = block.tr("\n", " ").squeeze(" ")
@@ -213,7 +175,7 @@ module Generators
 
       # Convert leading comment markers to spaces, but only
       # if all non-blank lines have them
-      
+
       if comment =~ /^(?>\s*)[^\#]/
         content = comment
       else
@@ -222,12 +184,11 @@ module Generators
       @markup.convert(content, @to_flow)
     end
 
-
-    # By default we replace existing classes with the
-    # same name. If the --merge option was given, we instead
-    # merge this definition into an existing class. We add
-    # our methods, aliases, etc to that class, but do not
-    # change the class's description.
+    ##
+    # By default we replace existing classes with the same name. If the
+    # --merge option was given, we instead merge this definition into an
+    # existing class. We add our methods, aliases, etc to that class, but do
+    # not change the class's description.
 
     def update_or_replace(cls_desc)
       old_cls = nil
@@ -242,7 +203,7 @@ module Generators
           $stderr.puts "documentation. This file references a class or "
           $stderr.puts "module called #{cls_desc.name} which I don't"
           $stderr.puts "have existing documentation for."
-          $stderr.puts 
+          $stderr.puts
           $stderr.puts "Perhaps you need to generate its documentation first"
           exit 1
         else
@@ -262,5 +223,8 @@ module Generators
         @ri_writer.add_class(old_desc)
       end
     end
+
   end
+
 end
+
diff --git a/lib/rdoc/generators/xml_generator.rb b/lib/rdoc/generators/xml_generator.rb
index 561a9ad694..8034fac517 100644
--- a/lib/rdoc/generators/xml_generator.rb
+++ b/lib/rdoc/generators/xml_generator.rb
@@ -1,4 +1,3 @@
-
 require 'rdoc/options'
 require 'rdoc/markup/simple_markup'
 require 'rdoc/markup/simple_markup/to_html'
@@ -6,16 +5,18 @@ require 'rdoc/generators/html_generator'
 
 module Generators
 
+  ##
   # Generate XML output as one big file
 
   class XMLGenerator < HTMLGenerator
 
+    ##
     # Standard generator factory
+
     def XMLGenerator.for(options)
       XMLGenerator.new(options)
     end
 
-    
     def initialize(*args)
       super
     end
@@ -23,7 +24,7 @@ module Generators
     ##
     # Build the initial indices and output objects
     # based on an array of TopLevel objects containing
-    # the extracted information. 
+    # the extracted information.
 
     def generate(info)
       @info       = info
@@ -35,7 +36,6 @@ module Generators
       generate_xml
     end
 
-
     ##
     # Generate:
     #
@@ -66,14 +66,14 @@ module Generators
     ##
     # Generate all the HTML. For the one-file case, we generate
     # all the information in to one big hash
-    #
+
     def generate_xml
-      values = { 
+      values = {
         'charset' => @options.charset,
         'files'   => gen_into(@files),
         'classes' => gen_into(@classes)
       }
-      
+
       # this method is defined in the template file
       write_extra_pages if defined? write_extra_pages
 
@@ -107,7 +107,6 @@ module Generators
       gen_an_index(HtmlMethod.all_methods, 'Methods')
     end
 
-    
     def gen_an_index(collection, title)
       res = []
       collection.sort.each do |f|
@@ -126,3 +125,4 @@ module Generators
   end
 
 end
+