Permalink
Browse files

documented the source annotation extractor

  • Loading branch information...
1 parent e6823bb commit 80bba28a1a56a0cafeb0fc94659905e88129bc31 @fxn fxn committed May 11, 2008
Showing with 41 additions and 0 deletions.
  1. +41 −0 railties/lib/source_annotation_extractor.rb
@@ -1,12 +1,40 @@
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]
s << text
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 @@ def initialize(tag)
@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 @@ def find_in(dir)
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 @@ def extract_annotations_from(file, pattern)
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}:"

0 comments on commit 80bba28

Please sign in to comment.