lazydoc 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2008, Regents of the University of Colorado.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,214 @@
+= Lazydoc[http://tap.rubyforge.org/lazydoc]
+
+Lazydoc lazily pulls documentation out of source files and makes it
+available in code through lazy attributes.  Lazydoc is used by the
+Tap[http://tap.rubyforge.org] framework.
+
+== Description
+
+Lazydoc can find two types of documentation: constant attributes and 
+code comments.  To illustrate, consider the following:
+
+  # Sample::key <value>
+  # This is the comment content.  A content
+  # string can span multiple lines...
+  #
+  #   code.is_allowed
+  #   much.as_in RDoc
+  #
+  # and stops at the next non-comment
+  # line, the next constant attribute,
+  # or an end key
+  class Sample
+    extend Lazydoc::Attributes
+    self.source_file = __FILE__
+
+    lazy_attr :key
+
+    # comment content for a code comment
+    # may similarly span multiple lines
+    def method_one
+    end
+  end
+
+When a lazy attribute is called, Lazydoc scans <tt>source_file</tt> for
+the corresponding constant attribute and makes it available as a
+Lazydoc::Comment.
+
+  comment = Sample::key
+  comment.value       
+  # => "<value>"
+
+  comment.content       
+  # => [
+  # ["This is the comment content.  A content", "string can span multiple lines..."],
+  # [""],
+  # ["  code.is_allowed"],
+  # ["  much.as_in RDoc"],
+  # [""],
+  # ["and stops at the next non-comment", "line, the next constant attribute,", "or an end key"]]
+
+  "\n#{'.' * 30}\n" + comment.wrap(30) + "\n#{'.' * 30}\n"
+  # => %q{
+  # ..............................
+  # This is the comment content.
+  # A content string can span
+  # multiple lines...
+  # 
+  #   code.is_allowed
+  #   much.as_in RDoc
+  # 
+  # and stops at the next
+  # non-comment line, the next
+  # constant attribute, or an end
+  # key
+  # ..............................
+  #}
+
+In addition, individual lines of code may be registered and resolved by Lazydoc:
+
+  doc = Sample.lazydoc.reset
+  comment = doc.register(/method_one/)
+  
+  doc.resolve
+  comment.subject       # => "  def method_one"
+  comment.content       # => [["comment content for a code comment", "may similarly span multiple lines"]]
+
+Check out these links for development, and bug tracking.
+
+* Website[http://tap.rubyforge.org/lazydoc]
+* Github[http://github.com/bahuvrihi/lazydoc/tree/master]
+* {Google Group}[http://groups.google.com/group/ruby-on-tap]
+
+== Usage
+
+=== Constant Attributes
+
+Constant attributes are like constants in Ruby, but with an extra 'key' 
+that must consist of only lowercase letters and/or underscores.  For 
+example, these are constant attributes:
+
+  # Const::Name::key
+  # Const::Name::key_with_underscores
+  # ::key
+
+While these are not:
+
+  # Const::Name::Key
+  # Const::Name::key2
+  # Const::Name::k@y
+
+Lazydoc parses a Lazydoc::Comment for each constant attribute by using the 
+remainder of the line as a value (ie subject) and scanning down for content.
+Scanning continues until a non-comment line, an end key, or a new attribute
+is reached; the comment is then stored by constant name and key.
+
+  str = %Q{
+  # Const::Name::key value for key
+  # comment for key
+  # parsed until a 
+  # non-comment line
+
+  # Const::Name::another value for another
+  # comment for another
+  # parsed to an end key
+  # Const::Name::another-
+  #
+  # ignored comment
+  }
+
+  doc = Lazydoc::Document.new
+  doc.resolve(str)
+
+  doc.to_hash {|comment| [comment.value, comment.to_s] } 
+  # => {
+  # 'Const::Name' => {
+  #   'key' =>     ['value for key', 'comment for key parsed until a non-comment line'],
+  #   'another' => ['value for another', 'comment for another parsed to an end key']}
+  # }
+
+Constant attributes are only parsed from commented lines.  To turn off
+attribute parsing for a section of documentation, use start/stop keys:
+
+  str = %Q{
+  Const::Name::not_parsed
+
+  # :::-
+  # Const::Name::not_parsed
+  # :::+
+  # Const::Name::parsed value
+  }
+
+  doc = Lazydoc::Document.new
+  doc.resolve(str)
+  doc.to_hash {|comment| comment.value }   # => {'Const::Name' => {'parsed' => 'value'}}
+
+To hide attributes from RDoc, make use of the RDoc <tt>:startdoc:</tt> 
+document modifier like this (note that spaces are added to prevent RDoc
+from hiding the example):
+
+  # :start doc::Const::Name::one hidden in RDoc
+  # * This line is visible in RDoc.
+  # :start doc::Const::Name::one-
+  # 
+  #-- 
+  # Const::Name::two
+  # You can hide attribute comments like this.
+  # Const::Name::two-
+  #++
+  #
+  # * This line is also visible in RDoc.
+
+As a side note, <tt>Const::Name::key</tt> is not a reference to the 'key' 
+constant (as that would be invalid).  In *very* idiomatic ruby
+<tt>Const::Name::key</tt> is equivalent to the method call 
+<tt>Const::Name.key</tt>.
+
+=== Code Comments
+
+Code comments are lines registered for parsing if and when a Lazydoc gets 
+resolved. Unlike constant attributes, the registered line is the comment
+subject (ie value) and contents are parsed up from it (basically mimicking
+the behavior of RDoc).
+
+  str = %Q{
+  # comment lines for
+  # the method
+  def method
+  end
+
+  # as in RDoc, the comment can be
+  # separated from the method
+
+  def another_method
+  end
+  }
+
+  doc = Lazydoc::Document.new
+  doc.register(3)
+  doc.register(9)
+  doc.resolve(str)
+
+  doc.comments.collect {|comment| [comment.subject, comment.to_s] } 
+  # => [
+  # ['def method', 'comment lines for the method'],
+  # ['def another_method', 'as in RDoc, the comment can be separated from the method']]
+
+Comments may be registered to specific line numbers, or with a Proc or
+Regexp that will determine the line number during resolution.  In the case
+of a Regexp, the first matching line is used; Procs receive an array of
+lines and should return the line number that should be used.  See 
+Lazydoc::Comment#resolve for more details.
+
+== Installation
+
+Lazydoc is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+
+  % gem install lazydoc
+
+== Info 
+
+Copyright (c) 2008, Regents of the University of Colorado.
+Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], {Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
+Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
+Licence:: {MIT-Style}[link:files/MIT-LICENSE.html]

data/lib/lazydoc/attributes.rb

@@ -0,0 +1,42 @@
+module Lazydoc
+  # Attributes adds methods to declare class-level accessors
+  # for Lazydoc attributes.  The source_file for the class must
+  # be set manually.
+  #
+  #   # ConstName::key value
+  #   class ConstName
+  #     class << self
+  #       include Lazydoc::Attributes
+  #     end
+  #
+  #     self.source_file = __FILE__
+  #     lazy_attr :key
+  #   end
+  #
+  #   ConstName::key.subject           # => 'value'
+  # 
+  module Attributes
+
+    # The source_file for self.  Must be set independently.
+    attr_accessor :source_file
+
+    # Returns the lazydoc for source_file
+    def lazydoc(resolve=true)
+      lazydoc = Lazydoc[source_file]
+      lazydoc.resolve if resolve
+      lazydoc
+    end
+
+    # Creates a lazy attribute accessor for the specified attribute.
+    def lazy_attr(key, attribute=key)
+      instance_eval %Q{
+def #{key}
+  lazydoc[to_s]['#{attribute}'] ||= Lazydoc::Comment.new
+end
+
+def #{key}=(comment)
+  Lazydoc[source_file][to_s]['#{attribute}'] = comment
+end}
+    end 
+  end
+end

data/lib/lazydoc/comment.rb

@@ -0,0 +1,499 @@
+require 'strscan'
+
+module Lazydoc
+  # Comment represents a code comment parsed by Lazydoc.  Comments consist
+  # of a subject and content.
+  #   
+  #   sample_comment = %Q{
+  #   # this is the content
+  #   #
+  #   # content may stretch across
+  #   # multiple lines
+  #   this is the subject
+  #   }
+  #   
+  # Normally the subject is the first non-comment line following the content,
+  # although in some cases the subject will be manually set to something else
+  # (as in a Lazydoc constant attribute). The content is an array of comment
+  # fragments organized by line:
+  #
+  #   c = Comment.parse(sample_comment)
+  #   c.subject      # => "this is the subject"
+  #   c.content      
+  #   # => [
+  #   # ["this is the content"], 
+  #   # [""], 
+  #   # ["content may stretch across", "multiple lines"]]
+  #
+  # Comments may be initialized to the subject line and then resolved later:
+  #
+  #   doc = %Q{
+  #   module Sample
+  #     # this is the content of the comment
+  #     # for method_one
+  #     def method_one
+  #     end
+  #
+  #     # this is the content of the comment
+  #     # for method_two
+  #     def method_two
+  #     end
+  #   end}
+  #
+  #   c1 = Comment.new(4).resolve(doc)
+  #   c1.subject     # => "  def method_one"
+  #   c1.content     # => [["this is the content of the comment", "for method_one"]]
+  #
+  #   c2 = Comment.new(9).resolve(doc)
+  #   c2.subject     # => "  def method_two"
+  #   c2.content     # => [["this is the content of the comment", "for method_two"]]
+  # 
+  # A Regexp (or Proc) may be used in place of a line number; during resolve,
+  # the lines will be scanned and the first matching line will be used.
+  #
+  #   c3 = Comment.new(/def method_two/).resolve(doc)
+  #   c3.subject     # => "  def method_two"
+  #   c3.content     # => [["this is the content of the comment", "for method_two"]]
+  #
+  class Comment
+
+    class << self
+  
+      # Parses the input string into a comment.  Takes a string or a 
+      # StringScanner and returns the comment.
+      #
+      #   comment_string = %Q{
+      #   # comments spanning multiple
+      #   # lines are collected
+      #   #
+      #   #   while indented lines
+      #   #   are preserved individually
+      #   #    
+      #   this is the subject line
+      #
+      #   # this line is not parsed
+      #   }
+      #
+      #   c = Comment.parse(comment_string)
+      #   c.content   
+      #   # => [
+      #   # ['comments spanning multiple', 'lines are collected'],
+      #   # [''],
+      #   # ['  while indented lines'],
+      #   # ['  are preserved individually'],
+      #   # [''],
+      #   # []]
+      #   c.subject   # => "this is the subject line"
+      #
+      # Parsing may be manually ended by providing a block; parse yields
+      # each line fragment to the block and stops parsing when the block
+      # returns true.  Note that no subject will be parsed under these
+      # circumstances.
+      #
+      #   c = Comment.parse(comment_string) {|frag| frag.strip.empty? }
+      #   c.content   
+      #   # => [
+      #   # ['comments spanning multiple', 'lines are collected']]
+      #   c.subject   # => nil
+      #
+      # Subject parsing may also be suppressed by setting parse_subject
+      # to false.
+      def parse(str, parse_subject=true) # :yields: fragment
+        scanner = case str
+        when StringScanner then str
+        when String then StringScanner.new(str)
+        else raise TypeError, "can't convert #{str.class} into StringScanner or String"
+        end
+    
+        comment = Comment.new
+        while scanner.scan(/\r?\n?[ \t]*#[ \t]?(([ \t]*).*?)\r?$/)
+          fragment = scanner[1]
+          indent = scanner[2]
+        
+          # collect continuous description line
+          # fragments and join into a single line
+          if block_given? && yield(fragment)
+            # break on comment if the description end is reached
+            parse_subject = false
+            break
+          else
+            categorize(fragment, indent) {|f| comment.push(f) }
+          end
+        end
+    
+        if parse_subject
+          scanner.skip(/\s+/)
+          unless scanner.peek(1) == '#'
+            comment.subject = scanner.scan(/.+?$/) 
+            comment.subject.strip! unless comment.subject == nil
+          end
+        end
+    
+        comment
+      end
+    
+      # Scan determines if and how to add a line fragment to a comment and
+      # yields the appropriate fragments to the block.  Returns true if
+      # fragments are yielded and false otherwise.  
+      #
+      # Content may be built from an array of lines using scan like so:
+      #
+      #   lines = [
+      #     "# comments spanning multiple",
+      #     "# lines are collected",
+      #     "#",
+      #     "#   while indented lines",
+      #     "#   are preserved individually",
+      #     "#    ",
+      #     "not a comment line",
+      #     "# skipped since the loop breaks",
+      #     "# at the first non-comment line"]
+      #
+      #   c = Comment.new
+      #   lines.each do |line|
+      #     break unless Comment.scan(line) do |fragment|
+      #       c.push(fragment)  
+      #     end
+      #   end
+      #
+      #   c.content   
+      #   # => [
+      #   # ['comments spanning multiple', 'lines are collected'],
+      #   # [''],
+      #   # ['  while indented lines'],
+      #   # ['  are preserved individually'],
+      #   # [''],
+      #   # []]
+      #
+      def scan(line) # :yields: fragment
+        return false unless line =~ /^[ \t]*#[ \t]?(([ \t]*).*?)\r?$/
+        categorize($1, $2) do |fragment|
+          yield(fragment)
+        end
+        true
+      end
+    
+      # Splits a line of text along whitespace breaks into fragments of cols
+      # width.  Tabs in the line will be expanded into tabsize spaces; 
+      # fragments are rstripped of whitespace.
+      # 
+      #   Comment.wrap("some line that will wrap", 10)       # => ["some line", "that will", "wrap"]
+      #   Comment.wrap("     line that will wrap    ", 10)   # => ["     line", "that will", "wrap"]
+      #   Comment.wrap("                            ", 10)   # => []
+      #
+      # The wrapping algorithm is slightly modified from:
+      # http://blog.macromates.com/2006/wrapping-text-with-regular-expressions/
+      def wrap(line, cols=80, tabsize=2)
+        line = line.gsub(/\t/, " " * tabsize) unless tabsize == nil
+        line.gsub(/(.{1,#{cols}})( +|$\r?\n?)|(.{1,#{cols}})/, "\\1\\3\n").split(/\s*?\n/)
+      end
+    
+      private
+    
+      # utility method used by scan to categorize and yield
+      # the appropriate objects to add the fragment to a
+      # comment
+      def categorize(fragment, indent) # :nodoc:
+        case
+        when fragment == indent
+          # empty comment line
+          yield [""]
+          yield []
+        when indent.empty?
+          # continuation line
+          yield fragment.rstrip
+        else 
+          # indented line
+          yield [fragment.rstrip]
+          yield []
+        end
+      end
+    end
+
+    # An array of comment fragments organized into lines
+    attr_reader :content
+
+    # The subject of the comment (normally set to the next 
+    # non-comment line after the content ends; ie the line 
+    # that would receive the comment in RDoc documentation)
+    attr_accessor :subject
+  
+    # Returns the line number for the subject line, if known.
+    # Although normally an integer, line_number may be
+    # set to a Regexp or Proc to dynamically determine
+    # the subject line during resolve
+    attr_accessor :line_number
+  
+    def initialize(line_number=nil)
+      @content = []
+      @subject = nil
+      @line_number = line_number
+    end
+    
+    # Alias for subject
+    def value
+      subject
+    end
+    
+    # Alias for subject=
+    def value=(value)
+      self.subject = value
+    end
+
+    # Pushes the fragment onto the last line array of content.  If the
+    # fragment is an array itself then it will be pushed onto content 
+    # as a new line.
+    #
+    #   c = Comment.new
+    #   c.push "some line"
+    #   c.push "fragments"
+    #   c.push ["a", "whole", "new line"]
+    #
+    #   c.content         
+    #   # => [
+    #   # ["some line", "fragments"], 
+    #   # ["a", "whole", "new line"]]
+    #
+    def push(fragment)
+      content << [] if content.empty?
+    
+      case fragment
+      when Array
+        if content[-1].empty? 
+          content[-1] = fragment
+        else
+          content.push fragment
+        end
+      else
+         content[-1].push fragment
+      end
+    end
+  
+    # Alias for push.
+    def <<(fragment)
+      push(fragment)
+    end
+  
+    # Scans the comment line using Comment.scan and pushes the appropriate
+    # fragments onto self.  Used to build a content by scanning down a set
+    # of lines.
+    #
+    #   lines = [
+    #     "# comment spanning multiple",
+    #     "# lines",
+    #     "#",
+    #     "#   indented line one",
+    #     "#   indented line two",
+    #     "#    ",
+    #     "not a comment line"]
+    #
+    #   c = Comment.new
+    #   lines.each {|line| c.append(line) }
+    #
+    #   c.content 
+    #   # => [
+    #   # ['comment spanning multiple', 'lines'],
+    #   # [''],
+    #   # ['  indented line one'],
+    #   # ['  indented line two'],
+    #   # [''],
+    #   # []]
+    #
+    def append(line)
+      Comment.scan(line) {|f| push(f) }
+    end
+  
+    # Unshifts the fragment to the first line array of content.  If the
+    # fragment is an array itself then it will be unshifted onto content
+    # as a new line.
+    #
+    #   c = Comment.new
+    #   c.unshift "some line"
+    #   c.unshift "fragments"
+    #   c.unshift ["a", "whole", "new line"]
+    #
+    #   c.content         
+    #   # => [
+    #   # ["a", "whole", "new line"], 
+    #   # ["fragments", "some line"]]
+    #
+    def unshift(fragment)
+      content << [] if content.empty?
+    
+      case fragment
+      when Array
+        if content[0].empty? 
+          content[0] = fragment
+        else
+          content.unshift fragment
+        end
+      else
+         content[0].unshift fragment
+      end
+    end
+  
+    # Scans the comment line using Comment.scan and unshifts the appropriate 
+    # fragments onto self.  Used to build a content by scanning up a set of
+    # lines.
+    #
+    #   lines = [
+    #     "# comment spanning multiple",
+    #     "# lines",
+    #     "#",
+    #     "#   indented line one",
+    #     "#   indented line two",
+    #     "#    ",
+    #     "not a comment line"]
+    #
+    #   c = Comment.new
+    #   lines.reverse_each {|line| c.prepend(line) }
+    #
+    #   c.content 
+    #   # => [
+    #   # ['comment spanning multiple', 'lines'],
+    #   # [''],
+    #   # ['  indented line one'],
+    #   # ['  indented line two'],
+    #   # ['']]
+    #
+    def prepend(line)
+      Comment.scan(line) {|f| unshift(f) }
+    end
+  
+    # Builds the subject and content of self using lines; resolve sets
+    # the subject to the line at line_number, and parses content up
+    # from there.  Any previously set subject and content is overridden.  
+    # Returns self.
+    #
+    #   document = %Q{
+    #   module Sample
+    #     # this is the content of the comment
+    #     # for method_one
+    #     def method_one
+    #     end
+    # 
+    #     # this is the content of the comment
+    #     # for method_two
+    #     def method_two
+    #     end
+    #   end}
+    #
+    #   c = Comment.new 4
+    #   c.resolve(document)
+    #   c.subject     # => "  def method_one"
+    #   c.content     # => [["this is the content of the comment", "for method_one"]]
+    #
+    # Lines may be an array or a string; string inputs are split into an
+    # array along newline boundaries.
+    #
+    # === dynamic line numbers
+    # The line_number used by resolve may be determined dynamically from
+    # lines by setting line_number to a Regexp and Proc. In the case
+    # of a Regexp, the first line matching the regexp is used:
+    #
+    #   c = Comment.new(/def method/)
+    #   c.resolve(document)
+    #   c.line_number = 4
+    #   c.subject     # => "  def method_one"
+    #   c.content     # => [["this is the content of the comment", "for method_one"]]
+    #
+    # Procs are called with lines and are expected to return the
+    # actual line number.  
+    #
+    #   c = Comment.new lambda {|lines| 9 }
+    #   c.resolve(document)
+    #   c.line_number = 9
+    #   c.subject     # => "  def method_two"
+    #   c.content     # => [["this is the content of the comment", "for method_two"]]
+    #
+    # As shown in the examples, in both cases the dynamically determined
+    # line_number overwrites the Regexp or Proc.
+    def resolve(lines)
+      lines = lines.split(/\r?\n/) if lines.kind_of?(String)
+    
+      # resolve late-evaluation line numbers
+      n = case line_number
+      when Regexp then match_index(line_number, lines)
+      when Proc then line_number.call(lines)
+      else line_number
+      end
+     
+      # quietly exit if a line number was not found
+      return self unless n.kind_of?(Integer)
+      
+      unless n < lines.length
+        raise RangeError, "line_number outside of lines: #{line_number} (#{lines.length})"
+      end
+    
+      self.line_number = n
+      self.subject = lines[n]
+      self.content.clear
+    
+      # remove whitespace lines
+      n -= 1
+      n -= 1 while n >=0 && lines[n].strip.empty?
+
+      # put together the comment
+      while n >= 0
+        break unless prepend(lines[n])
+        n -= 1
+      end
+     
+      self
+    end
+  
+    # Removes leading and trailing lines from content that are
+    # empty ([]) or whitespace (['']).  Returns self.
+    def trim
+      content.shift while !content.empty? && (content[0].empty? || content[0].join.strip.empty?)
+      content.pop   while !content.empty? && (content[-1].empty? || content[-1].join.strip.empty?)
+      self
+    end
+  
+    # True if all lines in content are empty.
+    def empty?
+      !content.find {|line| !line.empty?}
+    end
+  
+    # Returns content as a string where line fragments are joined by
+    # fragment_sep and lines are joined by line_sep. 
+    def to_s(fragment_sep=" ", line_sep="\n", strip=true)
+      lines = content.collect {|line| line.join(fragment_sep)}
+    
+      # strip leading an trailing whitespace lines
+      if strip
+        lines.shift while !lines.empty? && lines[0].empty?
+        lines.pop while !lines.empty? && lines[-1].empty?
+      end
+    
+      line_sep ? lines.join(line_sep) : lines
+    end
+  
+    # Like to_s, but wraps the content to the specified number of cols
+    # and expands tabs to tabsize spaces.
+    def wrap(cols=80, tabsize=2, line_sep="\n", fragment_sep=" ", strip=true)
+      lines = Comment.wrap(to_s(fragment_sep, "\n", strip), cols, tabsize)
+      line_sep ? lines.join(line_sep) : lines
+    end
+  
+    # Returns true if another is a Comment with the same
+    # line_number, subject, and content as self
+    def ==(another)
+      another.kind_of?(Comment) && 
+      self.line_number == another.line_number &&
+      self.subject == another.subject &&
+      self.content == another.content
+    end
+  
+    private
+  
+    # utility method used to by resolve to find the index
+    # of a line matching a regexp line_number.
+    def match_index(regexp, lines) # :nodoc:
+      lines.each_with_index do |line, index|
+        return index if line =~ regexp
+      end
+      nil
+    end
+  end
+end

data/lib/lazydoc/document.rb

@@ -0,0 +1,148 @@
+require 'lazydoc/comment'
+
+module Lazydoc
+  
+  # A Document tracks constant attributes and code comments for a particular
+  # source file.  Documents may be assigned a default_const_name to be used
+  # when a constant attribute does not specify a constant.
+  #
+  #   # KeyWithConst::key value a
+  #   # ::key value b
+  #
+  #   doc = Document.new(__FILE__, 'DefaultConst')
+  #   doc.resolve
+  #   doc['KeyWithConst']['key'].value      # => 'value a'
+  #   doc['DefaultConst']['key'].value      # => 'value b'
+  #
+  class Document
+    
+    # The source file for self, used during resolve
+    attr_reader :source_file
+  
+    # An array of Comment objects identifying lines 
+    # resolved or to-be-resolved
+    attr_reader :comments
+  
+    # A hash of [const_name, attributes] pairs tracking the constant 
+    # attributes resolved or to-be-resolved for self.  Attributes
+    # are hashes of [key, comment] pairs.
+    attr_reader :const_attrs
+  
+    # The default constant name used when no constant name
+    # is specified for a constant attribute
+    attr_reader :default_const_name
+  
+    # Flag indicating whether or not self has been resolved
+    attr_accessor :resolved
+  
+    def initialize(source_file=nil, default_const_name='')
+      self.source_file = source_file
+      @default_const_name = default_const_name
+      @comments = []
+      @const_attrs = {}
+      @resolved = false
+      self.reset
+    end
+  
+    # Resets self by clearing const_attrs, comments, and setting
+    # resolved to false.  Generally NOT recommended as this 
+    # clears any work you've done registering lines; to simply
+    # allow resolve to re-scan a document, manually set
+    # resolved to false.
+    def reset
+      @const_attrs.clear
+      @comments.clear
+      @resolved = false
+      self
+    end
+  
+    # Sets the source file for self.  Expands the source file path if necessary.
+    def source_file=(source_file)
+      @source_file = source_file == nil ? nil : File.expand_path(source_file)
+    end
+  
+    # Sets the default_const_name for self.  Any const_attrs assigned to 
+    # the previous default will be removed and merged with those already 
+    # assigned to the new default.
+    def default_const_name=(const_name)
+      self[const_name].merge!(const_attrs.delete(@default_const_name) || {})
+      @default_const_name = const_name
+    end
+  
+    # Returns the attributes for the specified const_name.
+    def [](const_name)
+      const_attrs[const_name] ||= {}
+    end
+    
+    # Returns an array of the const_names in self with at
+    # least one attribute.
+    def const_names
+      names = []
+      const_attrs.each_pair do |const_name, attrs|
+        names << const_name unless attrs.empty?
+      end
+      names
+    end
+    
+    # Register the specified line number to self.  Register
+    # may take an integer or a regexp for late-evaluation.
+    # See Comment#resolve for more details.
+    # 
+    # Returns a comment_class instance corresponding to the line.
+    def register(line_number, comment_class=Comment)
+      comment = comments.find {|c| c.class == comment_class && c.line_number == line_number }
+    
+      if comment == nil
+        comment = comment_class.new(line_number)
+        comments << comment
+      end
+    
+      comment
+    end
+    
+    # Registers a regexp matching methods by the specified
+    # name.
+    def register_method(method, comment_class=Comment)
+      register(/^\s*def\s+#{method}(\W|$)/, comment_class)
+    end
+  
+    # Scans str for constant attributes and adds them to to self.  Code
+    # comments are also resolved against str.  If no str is specified,
+    # the contents of source_file are used instead.
+    #
+    # Resolve does nothing if resolved == true.  Returns true if str
+    # was resolved, or false otherwise.
+    def resolve(str=nil)
+      return(false) if resolved
+    
+      str = File.read(source_file) if str == nil
+      Lazydoc.parse(str) do |const_name, key, comment|
+        const_name = default_const_name if const_name.empty?
+        self[const_name][key] = comment
+      end
+    
+      unless comments.empty?
+        lines = str.split(/\r?\n/)  
+        comments.each do |comment|
+          comment.resolve(lines)
+        end
+      end
+    
+      @resolved = true
+    end
+  
+    def to_hash
+      const_hash = {}
+      const_attrs.each_pair do |const_name, attributes|
+        next if attributes.empty?
+      
+        attr_hash = {}
+        attributes.each_pair do |key, comment|
+          attr_hash[key] = (block_given? ? yield(comment) : comment)
+        end
+        const_hash[const_name] = attr_hash
+      end
+      const_hash
+    end
+  end
+end

data/lib/lazydoc.rb

@@ -0,0 +1,180 @@
+require 'lazydoc/document'
+
+module Lazydoc
+  autoload(:Attributes, 'lazydoc/attributes')
+  
+  # A regexp matching an attribute start or end.  After a match:
+  #
+  # $1:: const_name
+  # $3:: key
+  # $4:: end flag
+  #
+  ATTRIBUTE_REGEXP = /([A-Z][A-z]*(::[A-Z][A-z]*)*)?::([a-z_]+)(-?)/
+
+  # A regexp matching constants from the ATTRIBUTE_REGEXP leader
+  CONSTANT_REGEXP = /#.*?([A-Z][A-z]*(::[A-Z][A-z]*)*)?$/
+  
+  # A regexp matching a caller line, to extract the calling file
+  # and line number.  After a match:
+  #
+  # $1:: file
+  # $3:: line number (as a string, obviously)
+  #
+  # Note that line numbers in caller start at 1, not 0.
+  CALLER_REGEXP = /^(([A-z]:)?[^:]+):(\d+)/
+  
+  module_function
+  
+  # A hash of (source_file, lazydoc) pairs tracking the
+  # Lazydoc instance for the given source file.
+  def registry
+    @registry ||= []
+  end
+  
+  # Returns the lazydoc in registry for the specified source file.
+  # If no such lazydoc exists, one will be created for it.
+  def [](source_file)
+    source_file = File.expand_path(source_file.to_s)
+    lazydoc = registry.find {|doc| doc.source_file == source_file }
+    if lazydoc == nil
+      lazydoc = Document.new(source_file)
+      registry << lazydoc
+    end
+    lazydoc
+  end
+
+  # Register the specified line numbers to the lazydoc for source_file.
+  # Returns a comment_class instance corresponding to the line.
+  def register(source_file, line_number, comment_class=Comment)
+    Lazydoc[source_file].register(line_number, comment_class)
+  end
+  
+  # Resolves all lazydocs which include the specified code comments.
+  def resolve_comments(comments)
+    registry.each do |doc|
+      next if (comments & doc.comments).empty?
+      doc.resolve
+    end
+  end
+  
+  # Scans the specified file for attributes keyed by key and stores 
+  # the resulting comments in the source_file lazydoc. Returns the
+  # lazydoc.
+  def scan_doc(source_file, key)
+    lazydoc = nil
+    scan(File.read(source_file), key) do |const_name, attr_key, comment|
+      lazydoc = self[source_file] unless lazydoc
+      lazydoc[const_name][attr_key] = comment
+    end
+    lazydoc
+  end
+  
+  # Scans the string or StringScanner for attributes matching the key
+  # (keys may be patterns, they are incorporated into a regexp). Yields 
+  # each (const_name, key, value) triplet to the mandatory block and
+  # skips regions delimited by the stop and start keys <tt>:-</tt> 
+  # and <tt>:+</tt>.
+  #
+  #   str = %Q{
+  #   # Const::Name::key value
+  #   # ::alt alt_value
+  #   #
+  #   # Ignored::Attribute::not_matched value
+  #   # :::-
+  #   # Also::Ignored::key value
+  #   # :::+
+  #   # Another::key another value
+  #
+  #   Ignored::key value
+  #   }
+  #
+  #   results = []
+  #   Lazydoc.scan(str, 'key|alt') do |const_name, key, value|
+  #     results << [const_name, key, value]
+  #   end
+  #
+  #   results    
+  #   # => [
+  #   # ['Const::Name', 'key', 'value'], 
+  #   # ['', 'alt', 'alt_value'], 
+  #   # ['Another', 'key', 'another value']]
+  #
+  # Returns the StringScanner used during scanning.
+  def scan(str, key) # :yields: const_name, key, value
+    scanner = case str
+    when StringScanner then str
+    when String then StringScanner.new(str)
+    else raise TypeError, "can't convert #{str.class} into StringScanner or String"
+    end
+
+    regexp = /^(.*?)::(:-|#{key})/
+    while !scanner.eos?
+      break if scanner.skip_until(regexp) == nil
+
+      if scanner[2] == ":-"
+        scanner.skip_until(/:::\+/)
+      else
+        next unless scanner[1] =~ CONSTANT_REGEXP
+        key = scanner[2]
+        yield($1.to_s, key, scanner.matched.strip) if scanner.scan(/[ \r\t].*$|$/)
+      end
+    end
+  
+    scanner
+  end
+
+  # Parses constant attributes from the string or StringScanner.  Yields 
+  # each (const_name, key, comment) triplet to the mandatory block 
+  # and skips regions delimited by the stop and start keys <tt>:-</tt> 
+  # and <tt>:+</tt>.
+  #
+  #   str = %Q{
+  #   # Const::Name::key subject for key
+  #   # comment for key
+  #
+  #   # :::-
+  #   # Ignored::key value
+  #   # :::+
+  #
+  #   # Ignored text before attribute ::another subject for another
+  #   # comment for another
+  #   }
+  #
+  #   results = []
+  #   Lazydoc.parse(str) do |const_name, key, comment|
+  #     results << [const_name, key, comment.subject, comment.to_s]
+  #   end
+  #
+  #   results    
+  #   # => [
+  #   # ['Const::Name', 'key', 'subject for key', 'comment for key'], 
+  #   # ['', 'another', 'subject for another', 'comment for another']]
+  #
+  # Returns the StringScanner used during scanning.
+  def parse(str) # :yields: const_name, key, comment
+    scanner = case str
+    when StringScanner then str
+    when String then StringScanner.new(str)
+    else raise TypeError, "can't convert #{str.class} into StringScanner or String"
+    end
+    
+    scan(scanner, '[a-z_]+') do |const_name, key, value|
+      comment = Comment.parse(scanner, false) do |line|
+        if line =~ ATTRIBUTE_REGEXP
+          # rewind to capture the next attribute unless an end is specified.
+          scanner.unscan unless $4 == '-' && $3 == key && $1.to_s == const_name
+          true
+        else false
+        end
+      end
+      comment.subject = value
+      yield(const_name, key, comment)
+    end
+  end
+  
+  def usage(path, cols=80)
+    scanner = StringScanner.new(File.read(path))
+    scanner.scan(/^#!.*?$/)
+    Comment.parse(scanner, false).wrap(cols, 2).strip
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: lazydoc
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Simon Chiang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-12 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: tap
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.11.1
+    version: 
+description: 
+email: simon.a.chiang@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- MIT-LICENSE
+files: 
+- lib/lazydoc.rb
+- lib/lazydoc/attributes.rb
+- lib/lazydoc/comment.rb
+- lib/lazydoc/document.rb
+- README
+- MIT-LICENSE
+has_rdoc: true
+homepage: http://tap.rubyforge.org/lazydoc
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: tap
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: lazydoc
+test_files: []
+