documented the source annotation extractor

railties/lib/source_annotation_extractor.rb

@@ -1,5 +1,27 @@
 class SourceAnnotationExtractor
+
+  # Implements the logic behind the rake tasks for annotations like
+  #
+  #   rake notes
+  #   rake notes:optimize
+  #
+  # and friends. See <tt>rake -T notes</tt> and <tt>railties/lib/tasks/annotations.rake</tt>.
+  #
+  # Annotation objects are triplets <tt>:line</tt>, <tt>:tag</tt>, <tt>:text</tt> that
+  # represent the line where the annotation lives, its tag, and its text. Note
+  # the filename is not stored.
+  #
+  # Annotations are looked for in comments and modulus whitespace they have to
+  # start with the tag optionally followed by a colon. Everything up to the end
+  # of the line (or closing ERb comment tag) is considered to be their text.
   class Annotation < Struct.new(:line, :tag, :text)
+
+    # Returns a representation of the annotation that looks like this:
+    #
+    #   [126] [TODO] This algorithm is simple and clearly correct, make it faster.
+    #
+    # If +options+ has a flag <tt>:tag</tt> the tag is shown as in the example above.
+    # Otherwise the string contains just line and text.
     def to_s(options={})
       s = "[%3d] " % line
       s << "[#{tag}] " if options[:tag]
@@ -7,6 +29,12 @@ class SourceAnnotationExtractor
     end
   end
 
+  # Prints all annotations with tag +tag+ under the root directories +app+, +lib+,
+  # and +test+ (recursively). Only filenames with extension +.builder+, +.rb+,
+  # +.rxml+, +.rjs+, +.rhtml+, or +.erb+ are taken into account. The +options+
+  # hash is passed to each annotation's +to_s+.
+  #
+  # This class method is the single entry point for the rake tasks.
   def self.enumerate(tag, options={})
     extractor = new(tag)
     extractor.display(extractor.find, options)
@@ -18,10 +46,18 @@ class SourceAnnotationExtractor
     @tag = tag
   end
 
+  # Returns a hash that maps filenames under +dirs+ (recursively) to arrays
+  # with their annotations. Only files with annotations are included, and only
+  # those with extension +.builder+, +.rb+, +.rxml+, +.rjs+, +.rhtml+, and +.erb+
+  # are taken into account.
   def find(dirs=%w(app lib test))
     dirs.inject({}) { |h, dir| h.update(find_in(dir)) }
   end
 
+  # Returns a hash that maps filenames under +dir+ (recursively) to arrays
+  # with their annotations. Only files with annotations are included, and only
+  # those with extension +.builder+, +.rb+, +.rxml+, +.rjs+, +.rhtml+, and +.erb+
+  # are taken into account.
   def find_in(dir)
     results = {}
 
@@ -40,6 +76,9 @@ class SourceAnnotationExtractor
     results
   end
 
+  # If +file+ is the filename of a file that contains annotations this method returns
+  # a hash with a single entry that maps +file+ to an array of its annotations.
+  # Otherwise it returns an empty hash.
   def extract_annotations_from(file, pattern)
     lineno = 0
     result = File.readlines(file).inject([]) do |list, line|
@@ -50,6 +89,8 @@ class SourceAnnotationExtractor
     result.empty? ? {} : { file => result }
   end
 
+  # Prints the mapping from filenames to annotations in +results+ ordered by filename.
+  # The +options+ hash is passed to each annotation's +to_s+.
   def display(results, options={})
     results.keys.sort.each do |file|
       puts "#{file}:"