lazydoc 0.9.0 → 1.0

data/History

@@ -1,3 +1,20 @@
+== 1.0.0 / 2009-12-05
+
+* optimized regexps
+* updated Lazydoc::Attributes to automatically set source_file
+  when inherited
+* added document method to Lazydoc to look up document for
+  source_file without automatically creating the document (as
+  is the case with Lazydoc[])
+* register_file now guesses a default constant name based on
+  the path relative to a matching LOAD_PATH
+* updated Lazydoc::Attributes to allow manually registered
+  comments across multiple source files
+* added inheritance for lazy attributes
+* changed registered_methods to return an array of the methods
+  whose documentation will be registered (no longer a hash by
+  default)
+  
 == 0.9.0 / 2009-05-25
 
 * lazy attributes can now be accessed without auto-resolve

data/MIT-LICENSE

@@ -1,19 +1,20 @@
 Copyright (c) 2008-2009, Regents of the University of Colorado.
+Copyright (c) 2009, Simon Chiang.
 
-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:
+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 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.
+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

@@ -6,9 +6,8 @@ Tap[http://tap.rubyforge.org] framework.
 
 == Description
 
-Lazydoc allows you to define lazy attributes that act as markers for
-documentation in a source file.  When you call the lazy attribute,
-Lazydoc pulls out the documentation:
+Lazydoc allows you to define lazy attributes that access documentation in a
+source file.
 
   # Sample::key <value>
   # This is the comment content.  A content
@@ -35,8 +34,7 @@ Comments support wrapping, allowing for easy presentation:
   # ..............................
   # }
 
-In addition, Lazydoc provides helpers to register individual lines of code, 
-particularly method definitions:
+Lazydoc also provides helpers to register method documentation:
 
   class Helpers
     extend Lazydoc::Attributes
@@ -49,7 +47,7 @@ particularly method definitions:
     end
     
     # register_caller will register the line
-    # that *calls* method_two
+    # that *calls* method_two (see below)
     def method_two
       Lazydoc.register_caller
     end
@@ -59,19 +57,18 @@ particularly method definitions:
   # registered by method_two
   Helpers.const_attrs[:method_two] = Helpers.new.method_two
   
-  doc = Helpers.lazydoc
-  doc.resolve
-  
   one = Helpers.const_attrs[:method_one]
+  one.resolve
   one.method_name            # => "method_one"
   one.arguments              # => ["a", "b='str'", "&c"]
   one.to_s                   # => "method_one is registered whenever it gets defined"
   
   two = Helpers.const_attrs[:method_two]
+  two.resolve
   two.subject                # => "Helpers.const_attrs[:method_two] = Helpers.new.method_two"
   two.to_s                   # => "*THIS* is the line that gets registered by method_two"
 
-Lazy accessors may be defined to map the registered lines as well:
+Lazy accessors may be defined to access the registered lines more easily:
 
   class Helpers
     lazy_attr(:one, :method_one)
@@ -81,11 +78,10 @@ Lazy accessors may be defined to map the registered lines as well:
   Helpers.one.method_name    # => "method_one"
   Helpers.two.subject        # => "Helpers.const_attrs[:method_two] = Helpers.new.method_two"
 
-Check out these links for development, and bug tracking.
+Check out these links for developments and bug tracking.
 
 * Website[http://tap.rubyforge.org/lazydoc]
 * Github[http://github.com/bahuvrihi/lazydoc/tree/master]
-* Lighthouse[http://bahuvrihi.lighthouseapp.com/projects/19948-lazydoc/tickets?q=all]
 * {Google Group}[http://groups.google.com/group/ruby-on-tap]
 
 == Usage
@@ -96,9 +92,9 @@ are represented by Comment objects.
 
 === 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:
+Constant attributes are defined in the documentation to look like constants,
+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
@@ -111,7 +107,7 @@ While these are not:
   # 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 parsing down for content.
+remainder of the line as a value (ie subject) and trailing lines as content.
 Parsing 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.
 
@@ -139,8 +135,8 @@ is reached; the comment is then stored by constant name and key.
   #   '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:
+Constant attributes are only parsed from comment lines. To turn off attribute
+parsing for a section of documentation, use start/stop keys:
 
   str = %Q{
   Const::Name::not_parsed
@@ -155,9 +151,9 @@ attribute parsing for a section of documentation, use start/stop keys:
   doc.resolve(str)
   doc.summarize {|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):
+To hide attributes from RDoc, make use of the RDoc <tt>:startdoc:</tt>
+document modifier like this (note the modifiers have an extra space in them to
+prevent RDoc from hiding the example):
 
   # :start doc::Const::Name::one hidden in RDoc
   # * This line is visible in RDoc.
@@ -171,16 +167,17 @@ from hiding the example):
   #
   # * This line is also visible in RDoc.
 
-As a side note, 'Const::Name::key' is not a reference to the 'key' 
-constant (that would be invalid).  In *very* idiomatic ruby
-'Const::Name::key' is equivalent to the method call 'Const::Name.key'.
+As a side note, the constant attribute syntax is designed to echo how the
+Lazydoc::Attributes module makes comments accessible in code. In *very*
+idiomatic Ruby 'Const::Name::key' is equivalent to the method call
+'Const::Name.key'.
 
 === Code Comments
 
-Code comments are lines registered for parsing if and when a Lazydoc gets 
+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).
+subject (ie value) and the content consists of the preceding documentation
+(basically mimicking the behavior of RDoc).
 
   str = %Q{
   # comment lines for
@@ -211,6 +208,31 @@ 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 
 {Comment#parse_up}[link://classes/Lazydoc/Comment.html] for more details.
 
+Manually registering lines for documentation can be quite cumbersome. The
+Lazydoc::Attributes module provides helpers to register method documentation
+on classes with method-like inheritance.
+
+  class A
+    extend Lazydoc::Attributes
+    lazy_attr(:one, :method_one)
+    lazy_register(:method_one)
+    
+    # documentation for method one
+    def method_one; end
+  end
+  
+  class B < A
+  end
+  
+  class C < B
+    # overriding documentation for method one
+    def method_one; end
+  end
+  
+  A::one.comment    # => "documentation for method one"
+  B::one.comment    # => "documentation for method one"
+  C::one.comment    # => "overriding documentation for method one"
+
 == Installation
 
 Lazydoc is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
@@ -219,7 +241,6 @@ Lazydoc is available as a gem on RubyForge[http://rubyforge.org/projects/tap].
 
 == Info 
 
-Copyright (c) 2008-2009, 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
+Copyright (c) 2009, Simon Chiang.
+Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com]
 License:: {MIT-Style}[link:files/MIT-LICENSE.html]

data/lib/lazydoc.rb

@@ -1,3 +1,4 @@
+require 'lazydoc/version'
 require 'lazydoc/document'
 
 module Lazydoc
@@ -8,22 +9,54 @@ module Lazydoc
     @registry ||= []
   end
   
-  # Returns the Document in registry for the specified source file.
-  # If no such Document exists, one will be created for it.
+  # Returns the document registered to the source file, or nil if no such
+  # document exists.
+  def document(source_file)
+    source_file = File.expand_path(source_file.to_s)
+    registry.find {|doc| doc.source_file == source_file }
+  end
+  
+  # Returns the document registered to the source file.  If no such document
+  # exists, one will be created for it.
   def [](source_file)
+    document(source_file) || register_file(source_file)
+  end
+  
+  # Guesses the default constant name for the source file by camelizing the
+  # shortest relative path from a matching $LOAD_PATH to the source file.
+  # Returns nil if the source file is not relative to any load path.
+  #
+  # ==== Code Credit
+  #
+  # The camelize algorithm is taken from the ActiveSupport {Inflections}[http://api.rubyonrails.org/classes/ActiveSupport/CoreExtensions/String/Inflections.html]
+  # module.  See the {Tap::Env::StringExt}[http://tap.rubyforge.org/rdoc/classes/Tap/Env/StringExt.html]
+  # module (which uses the same) for a proper credit and license.
+  #
+  def guess_const_name(source_file)
     source_file = File.expand_path(source_file.to_s)
-    registry.find {|doc| doc.source_file == source_file } || register_file(source_file)
+    
+    load_paths = []
+    $LOAD_PATH.each do |load_path|
+      load_path = File.expand_path(load_path)
+      if source_file.rindex(load_path, 0) == 0
+        load_paths << load_path
+      end
+    end
+    
+    return nil if load_paths.empty?
+    
+    load_path = load_paths.sort_by {|load_path| load_path.length}.pop
+    extname = File.extname(source_file)
+    relative_path = source_file[(load_path.length + 1)..(-1 - extname.length)]
+    relative_path.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
   end
   
-  # Generates a Document the source_file and default_const_name and adds it to
-  # registry, or returns the document already registered to source_file.  An
+  # Generates a document for the source_file and default_const_name and adds it to
+  # registry, or returns the document already registered to the source file.  An
   # error is raised if you try to re-register a source_file with an inconsistent
   # default_const_name.
-  def register_file(source_file, default_const_name=nil)
-    source_file = File.expand_path(source_file.to_s)
-    lazydoc = registry.find {|doc| doc.source_file == source_file }
-    
-    unless lazydoc
+  def register_file(source_file, default_const_name=guess_const_name(source_file))
+    unless lazydoc = document(source_file)
       lazydoc = Document.new(source_file)
       registry << lazydoc
     end
@@ -32,16 +65,15 @@ module Lazydoc
     lazydoc
   end
 
-  # Registers the line number to the document for source_file and
-  # returns the corresponding comment.
+  # Registers the line number to the document for source_file and returns the
+  # new comment.
   def register(source_file, line_number, comment_class=Comment)
     Lazydoc[source_file].register(line_number, comment_class)
   end
   
-  # Registers the method at the specified index in the call stack to
-  # the file where the method was called.  Using the default index of
-  # 1, register_caller registers the caller of the method where 
-  # register_caller is called (whew!).  For instance:
+  # Registers the method to the line where it was called.  To do so,
+  # register_caller examines the specified index in the call stack
+  # and extracts a file and line number.  For instance:
   #
   #   module Sample
   #     module_function
@@ -59,7 +91,7 @@ module Lazydoc
   #
   def register_caller(comment_class=Comment, caller_index=1)
     caller[caller_index] =~ CALLER_REGEXP
-    Lazydoc[$1].register($3.to_i - 1, comment_class)
+    Lazydoc[$1].register($2.to_i - 1, comment_class)
   end
   
   # Parses the usage for a file (ie the first comment in the file 

data/lib/lazydoc/attributes.rb

@@ -1,7 +1,7 @@
 module Lazydoc
   
   # Attributes adds methods to declare class-level accessors for constant
-  # attributes.
+  # attributes associated with the class.
   #
   #   # ConstName::key value
   #   class ConstName
@@ -9,132 +9,287 @@ module Lazydoc
   #     lazy_attr :key
   #   end
   #
-  #   ConstName.source_file            # =>  __FILE__
-  #   ConstName::key.subject           # => 'value'
+  #   ConstName::key.subject                 # => 'value'
+  #
+  # Lazy attributes are inherited, but can be overridden.
+  #
+  #   class SubclassA < ConstName; end
+  #   SubclassA::key.subject                 # => 'value'
+  #
+  #   # SubclassB::key overridden value
+  #   class SubclassB < ConstName; end
+  #   SubclassB::key.subject                 # => 'overridden value'
+  #
+  # You can use Attributes to register methods on modules, but currently the
+  # inheritance is a bit wonky; the accessors are methods on the extended
+  # class/module and so standard module inclusion will not pass them on.
+  # To work around you need to extend and redefine the accessors.  Note,
+  # however, that methods do not need to be re-registered.
+  #
+  #   module A
+  #     extend Lazydoc::Attributes
+  #     lazy_attr(:one, :method_one)
+  #     lazy_register(:method_one)
+  #   
+  #     # documentation for method one
+  #     def method_one; end
+  #   end
   # 
+  #   class B
+  #     include A
+  #     extend Lazydoc::Attributes
+  #     lazy_attr(:one, :method_one)
+  #   end
+  # 
+  #   class C < B
+  #     # overriding documentation for method one
+  #     def method_one; end
+  #   end
+  # 
+  #   A::one.comment    # => "documentation for method one"
+  #   B::one.comment    # => "documentation for method one"
+  #   C::one.comment    # => "overriding documentation for method one"
+  #   
   # ==== Keys and Register
   #
-  # Note that constant attributes parsed from a source file are stored in
-  # const_attrs, and will ALWAYS be keyed using a string (since the 
-  # 'ConstName::key' syntax specifies a string key).
+  # Constant attributes parsed from a source file will ALWAYS be stored in
+  # const_attrs using a string (since the 'ConstName::key' syntax always
+  # results in a string key).  A lazy_attr is basically shorthand for either
+  # of these statements:
+  #
+  #   ConstName.const_attrs['key'].subject            # => 'value'
+  #   Lazydoc::Document['ConstName']['key'].subject   # => 'value'
+  #
+  # By default a lazy_attr maps to the constant attribute with the same name
+  # as the accessor, but this can be overridden by specifying the string key
+  # for another attribute.
+  #
+  #   class ConstName
+  #     lazy_attr :alt, 'key'
+  #   end
   #
-  #   ConstName.const_attrs['key']     # => ConstName::key
+  #   ConstName::alt.subject                     # => 'value'
+  #   ConstName.const_attrs['alt']               # => nil
   #
-  # 'Constant Attributes' specified by non-string keys are sometimes used to
-  # tie comments to a constant that will NOT be resolved from the constant
-  # attribute syntax.  For instance you could register a method like this:
+  # Comments specified by non-string keys may also be stored in const_attrs;
+  # these will not conflict with constant attributes parsed from a source
+  # file. For instance you could manually register a comment to a symbol key
+  # using lazy_register:
   #
   #   class Sample
   #     extend Lazydoc::Attributes
   #
-  #     const_attrs[:method_one] = register___
+  #     lazy_register(:method_one)
+  #
   #     # this is the method one comment
   #     def method_one
   #     end
   #   end
   #
-  #   Sample.lazydoc.resolve
-  #   Sample.const_attrs[:method_one].comment   # => "this is the method one comment"
+  #   Sample.const_attrs[:method_one].comment    # => "this is the method one comment"
   # 
-  # For easier access, you could define a lazy_attr to access the registered
-  # comment.  And in the simplest case, you pair a lazy_register with a
-  # lazy_attr.
+  # Manually-registered comments may then be paired with a lazy_attr.  As
+  # before the key for the comment is provided in the definition.
   #
   #   class Paired
   #     extend Lazydoc::Attributes
   #
   #     lazy_attr(:one, :method_one)
-  #     lazy_attr(:two, :method_two)
-  #     lazy_register(:method_two)
+  #     lazy_register(:method_one)
   #
-  #     const_attrs[:method_one] = register___
-  #     # this is the manually-registered method one comment
+  #     # this is the method one comment
   #     def method_one
   #     end
-  #
-  #     # this is the lazyily-registered method two comment
-  #     def method_two
-  #     end
   #   end
   #
-  #   Paired.lazydoc.resolve
-  #   Paired.one.comment      # => "this is the manually-registered method one comment"
-  #   Paired.two.comment      # => "this is the lazyily-registered method two comment"
+  #   Paired::one.comment   # => "this is the method one comment"
+  #
+  # ==== Troubleshooting
   #
+  # Under most circumstances Attributes will register all the necessary files
+  # to make constant attributes available.  These include:
+  #
+  # * the file where the class is extended
+  # * the file where a subclass inherits from an extended class
+  # * files that declare a lazy_attr
+  #
+  # Be sure to call register_lazydoc in files that are not covered by one of
+  # these cases but nonetheless contain constant attributes that should be
+  # available to a lazy_attr.
   module Attributes
-
-    # The source file for the extended class.  By default source_file
-    # is set to the file where Attributes extends the class (if you 
-    # include Attributes, you must set source_file manually).
-    attr_accessor :source_file
     
-    def self.extended(base) # :nodoc:
+    # Sets source_file as the file where Attributes first extends the class.
+    def self.extended(base)
       caller[1] =~ CALLER_REGEXP
-      base.source_file ||= $1
-    end
-    
-    # Inherits registered_methods from parent to child.
-    def inherited(child)
-      child.registered_methods.merge!(registered_methods)
+      unless base.instance_variable_defined?(:@lazydocs)
+        base.instance_variable_set(:@lazydocs, [Lazydoc[$1]])
+      end
+      
+      unless base.instance_variable_defined?(:@lazy_registry)
+        base.instance_variable_set(:@lazy_registry, {})
+      end
+      
       super
     end
     
-    # Lazily registers the added method if marked for lazy registration.
-    def method_added(sym)
-      if args = registered_methods[sym]
-        const_attrs[sym] ||= Lazydoc.register_caller(*args)
+    # Returns the documents registered to the extending class.
+    # 
+    # By default lazydocs contains a Document for the file where Attributes
+    # extends the class, or where a subclass first inherits from an extended
+    # class (if you include Attributes, you must set lazydocs manually).
+    #
+    # Additional documents may be added by calling register_lazydoc.
+    attr_reader :lazydocs
+    
+    # Returns an array of the methods whose documentation will be automatically
+    # registered by Attributes.  Set as_registry to true to return a hash of
+    # of (method_name, [comment_class, caller_index]) pairs where the 
+    # registration arguments are the hash values.
+    def registered_methods(as_registry=false)
+      methods = {}
+      ancestors.reverse.each do |ancestor|
+        if ancestor.kind_of?(Attributes)
+          methods.merge!(ancestor.lazy_registry)
+        end
       end
       
-      super
+      as_registry ? methods : methods.keys
     end
     
     # Returns the constant attributes resolved for the extended class.
     def const_attrs
       Document[to_s]
     end
-
-    # Returns the Document for source_file
-    def lazydoc
-      Lazydoc[source_file]
-    end
+    
+    protected
     
     # A hash of (method_name, [comment_class, caller_index]) pairs indicating
-    # methods to lazily register, and the inputs to Lazydoc.register_caller
-    # used to register the method.
-    def registered_methods
-      @registered_methods ||= {}
+    # methods to lazily register, and the inputs used to register the method.
+    #
+    # The lazy_registry only contains methods lazily registered within the
+    # current class or module.  To return methods registered throughout the
+    # inheritance hierarchy, use registered_methods(true)
+    attr_reader :lazy_registry
+    
+    # Registers the calling file into lazydocs.  Registration occurs by
+    # examining the call stack at the specified index.
+    def register_lazydoc(caller_index=0)
+      caller[caller_index] =~ CALLER_REGEXP
+      lazydocs << Lazydoc[File.expand_path($1)]
+      lazydocs.uniq!
+      self
     end
     
     # Creates a method that reads and resolves the constant attribute specified
-    # by key, which should normally be a string (see above for more details).  
-    # If writable is true, a corresponding writer is also created.
+    # by key. The method has a signature like:
+    #
+    #   def method(resolve=true)
+    #   end
+    #
+    # To return the constant attribute without resolving, call the method with
+    # resolve == false. If writable is true, a corresponding writer is also
+    # created.
     def lazy_attr(symbol, key=symbol.to_s, writable=true)
-      key = case key
-      when String, Symbol, Numeric, true, false, nil then key.inspect
-      else "YAML.load(\'#{YAML.dump(key)}\')"
+      unless key.kind_of?(String) || key.kind_of?(Symbol)
+        raise "invalid lazy_attr key: #{key.inspect} (#{key.class})"
       end
       
-      instance_eval %Q{
-def #{symbol}(resolve=true)
-  comment = const_attrs[#{key}] ||= Subject.new(nil, lazydoc)
-  resolve && comment.kind_of?(Comment) ? comment.resolve : comment
-end}
-
-      instance_eval(%Q{
-def #{symbol}=(comment)
-  const_attrs[#{key}] = comment
-end}) if writable
+      key = key.inspect
+      instance_eval %Q{def #{symbol}(resolve=true); get_const_attr(#{key}, resolve); end}
+      instance_eval(%Q{def #{symbol}=(comment); const_attrs[#{key}] = comment; end}) if writable
+      
+      register_lazydoc(1)
     end
     
     # Marks the method for lazy registration.  When the method is registered,
     # it will be stored in const_attrs by method_name.
     def lazy_register(method_name, comment_class=Method, caller_index=1)
-      registered_methods[method_name.to_sym] = [comment_class, caller_index]
+      lazy_registry[method_name.to_sym] = [comment_class, caller_index]
     end
     
-    # Registers the next comment (by default as a Method).
-    def register___(comment_class=Method)
-      lazydoc.register___(comment_class, 1)
+    # Manually registers the next comment into const_attrs.  Note a lazy_attr
+    # will still need to be defined to access this comment as an attribute.
+    def register___(key, comment_class=Method)
+      caller[0] =~ CALLER_REGEXP
+      source_file = File.expand_path($1)
+      const_attrs[key] = Lazydoc[source_file].register___(comment_class, 1)
+    end
+    
+    private
+    
+    # Inherits lazy_registry from parent to child.  Also registers the
+    # source_file for the child as the file where the inheritance first
+    # occurs.
+    def inherited(child)
+      unless child.instance_variable_defined?(:@lazydocs)
+        caller.each do |call|
+          next if call =~ /in `inherited'$/
+          
+          call =~ CALLER_REGEXP
+          child.instance_variable_set(:@lazydocs, [Lazydoc[$1]])
+          break
+        end
+      end
+      
+      unless child.instance_variable_defined?(:@lazy_registry)
+        child.instance_variable_set(:@lazy_registry, {})
+      end
+      
+      super
+    end
+    
+    # Helper to traverse the inheritance hierarchy.  The logic of this method
+    # is described in the dsl pattern: http://gist.github.com/181961
+    def each_ancestor # :nodoc:
+      yield(self)
+      
+      blank, *ancestors = self.ancestors
+      ancestors.each do |ancestor|
+        yield(ancestor) if ancestor.kind_of?(Attributes)
+      end
+      
+      nil
+    end
+    
+    # Lazily registers the added method if marked for lazy registration.
+    def method_added(sym)
+      current = nil
+      each_ancestor do |ancestor|
+        if ancestor.lazy_registry.has_key?(sym)
+          current = ancestor
+          break
+        end
+      end
+    
+      if current
+        args = current.lazy_registry[sym]
+        const_attrs[sym] ||= Lazydoc.register_caller(*args)
+      end
+    
+      super
+    end
+  
+    # helper to traverse up the inheritance hierarchy looking for the first
+    # const_attr assigned to key.  the lazydocs for each class will be
+    # resolved along the way, if specified.
+    def get_const_attr(key, resolve) # :nodoc:
+      each_ancestor do |ancestor|
+        const_attrs = ancestor.const_attrs
+      
+        unless const_attrs.has_key?(key)
+          next unless resolve
+        
+          ancestor.lazydocs.each {|doc| doc.resolve }
+          next unless const_attrs.has_key?(key)
+        end
+      
+        const_attr = const_attrs[key]
+        if resolve && const_attr.kind_of?(Comment)
+          const_attr.resolve
+        end
+
+        return const_attr
+      end
     end
   end
 end

data/lib/lazydoc/document.rb

@@ -10,22 +10,22 @@ module Lazydoc
   # A regexp matching an attribute start or end.  After a match:
   #
   #   $1:: const_name
-  #   $3:: key
-  #   $4:: end flag
+  #   $2:: key
+  #   $3:: end flag
   #
-  ATTRIBUTE_REGEXP = /([A-Z][A-z]*(::[A-Z][A-z]*)*)?::([a-z_]+)(-?)/
+  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]*)*)?$/
+  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)
+  #   $2:: line number (as a string, obviously)
   #
   # Note that line numbers in caller start at 1, not 0.
-  CALLER_REGEXP = /^(([A-z]:)?[^:]+):(\d+)/
+  CALLER_REGEXP = /^((?:[A-z]:)?[^:]+):(\d+)/
   
   # A Document resolves constant attributes and code comments for a particular
   # source file.  Documents may be assigned a default_const_name to be used 
@@ -40,9 +40,8 @@ module Lazydoc
   #   Document['Const::Name']['key'].value      # => 'value a'
   #   Document['Default']['key'].value          # => 'value b'
   #
-  # As shown in the example, constant attibutes for all documents are cached in
-  # the class-level const_attrs hash and are normally consumed through Document 
-  # itself.
+  # As in the example, constant attibutes for all documents may be accessed
+  # from Document[].
   class Document
     class << self
       
@@ -136,6 +135,9 @@ module Lazydoc
     # Returns the attributes for the specified const_name.  If an empty 
     # const_name ('') is specified, and a default_const_name is set,
     # the default_const_name will be used instead.
+    #
+    # Note this method will return ALL attributes associated with const_name,
+    # not just attributes associated with self.
     def [](const_name)
       const_name = default_const_name if default_const_name && const_name == ''
       Document[const_name]
@@ -184,7 +186,7 @@ module Lazydoc
     def register___(comment_class=Comment, caller_index=0)
       caller[caller_index] =~ CALLER_REGEXP
       block = lambda do |scanner, lines|
-        n = $3.to_i
+        n = $2.to_i
         n += 1 while lines[n] =~ /^\s*(#.*)?$/
         n
       end
@@ -216,7 +218,7 @@ module Lazydoc
         comment.parse_down(scanner, lines) 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
+            scanner.unscan unless $3 == '-' && $2 == key && $1.to_s == const_name
             true
           else false
           end

data/lib/lazydoc/version.rb

@@ -0,0 +1,7 @@
+module Lazydoc
+  MAJOR = 1
+  MINOR = 0
+  TINY = 0
+  
+  VERSION="#{MAJOR}.#{MINOR}.#{TINY}"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: lazydoc
 version: !ruby/object:Gem::Version 
-  version: 0.9.0
+  version: "1.0"
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-25 00:00:00 -06:00
+date: 2009-12-05 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -33,11 +33,14 @@ files:
 - lib/lazydoc/subject.rb
 - lib/lazydoc/trailer.rb
 - lib/lazydoc/utils.rb
+- lib/lazydoc/version.rb
 - README
 - MIT-LICENSE
 - History
 has_rdoc: true
 homepage: http://tap.rubyforge.org/lazydoc
+licenses: []
+
 post_install_message: 
 rdoc_options: 
 - --title
@@ -63,9 +66,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: tap
-rubygems_version: 1.3.1
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: Lazily pull documentation out of source files.
 test_files: []