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