aquarium 0.4.1 → 0.4.2

data/lib/aquarium/aspects/default_objects_handler.rb

@@ -3,10 +3,12 @@ require 'set'
 
 module Aquarium
   module Aspects
-    # Some classes and modules support a :default_objects flag and use it if no type or
-    # object is specified. For "convenience", requires that classes and modules including
-    # this module have a hash @specification defined with keys :default_objects, :types,
-    # and :objects.
+    # Some classes support a <tt>:default_objects</tt> option and use it if no type or
+    # object is specified. In other words, the <tt>:default_objects</tt> option is ignored
+    # if  <tt>:types</tt> or <tt>:objects</tt> is present.
+    # This module handles this behavior for all the classes that include it. These classes 
+    # are assumed to have <tt>@specification</tt> defined with keys 
+    # <tt>:default_objects</tt>, <tt>:types</tt>, and <tt>:objects</tt>.
     module DefaultObjectsHandler
       include Aquarium::Utils::ArrayUtils
       

data/lib/aquarium/aspects/exclusion_handler.rb

@@ -1,22 +1,33 @@
+require 'aquarium/utils/set_utils'
 
 module Aquarium
   module Aspects
     
-    # Defines methods shared by several classes that take :exclude_* arguments.
+    # Defines methods shared by several classes that take <tt>:exclude_*</tt> arguments.
     module ExclusionHandler
+      include Aquarium::Utils::HashUtils
       
       def join_point_excluded? jp
         is_excluded_pointcut?(jp) or is_excluded_join_point?(jp) or is_excluded_type_or_object?(jp.type_or_object) or is_excluded_method?(jp.method_name)
       end
       
       def is_excluded_pointcut? jp
-        return false if @specification[:exclude_pointcuts].nil?
-        @specification[:exclude_pointcuts].find do |pc|
+        return false if all_excluded_pointcuts.empty?
+        all_excluded_pointcuts.find do |pc|
           pc.join_points_matched.find do |jp2|
             jp2 == jp || jp2.eql?(jp)
           end
         end
       end
+      
+      def set_calculated_excluded_pointcuts excluded_pointcuts
+        @calculated_excluded_pointcuts = excluded_pointcuts
+        @all_excluded_pointcuts = @specification[:exclude_pointcuts] | Set.new(@calculated_excluded_pointcuts)
+      end
+      
+      def all_excluded_pointcuts
+        @all_excluded_pointcuts ||= @specification[:exclude_pointcuts]
+      end        
 
       # Using @specification[:exclude_join_points].include?(jp) doesn't always work correctly (it probably uses equal?())!
       def is_excluded_join_point? jp
@@ -56,6 +67,7 @@ module Aquarium
         return false if regexs.empty?
         regexs.find {|re| method.to_s =~ re}          
       end
+      
     end
   end
 end

data/lib/aquarium/aspects/join_point.rb

@@ -1,4 +1,5 @@
 require 'aquarium/utils'
+require 'aquarium/aspects/advice'
   
 def bad_attributes message, options
   raise Aquarium::Utils::InvalidOptions.new("Invalid attributes. " + message + ". Options were: #{options.inspect}")
@@ -6,57 +7,54 @@ end
 
 module Aquarium
   module Aspects
+    # == JoinPoint
+    # Encapsulates information about a Join Point that might be advised. JoinPoint objects are <i>almost</i> 
+    # value objects; you can change the context object.
+    # TODO Separate out the read-only part from the variable part. This might require an API change!
     class JoinPoint
 
       class ProceedMethodNotAvailable < Exception; end
-      class ContextNotDefined < Exception; end
+      class ContextNotCorrectlyDefined < Exception; end
       
+      # == JoinPoint::Context
+      # Encapsulates current runtime context information for a join point, such as the values of method parameters, a raised 
+      # exception (for <tt>:after</tt> or <tt>after_raising</tt> advice), <i>etc.</i>
+      # Context objects are <i>partly</i> value objects. 
+      # TODO Separate out the read-only part from the variable part. This might require an API change!
       class Context
-        attr_accessor :advice_kind, :advised_object, :parameters, :block_for_method, :returned_value, :raised_exception, :proceed_proc, :current_advice_node
+        attr_accessor :advice_kind, :advised_object, :parameters, :proceed_proc, :current_advice_node
+        attr_accessor :returned_value, :raised_exception, :block_for_method
 
         alias :target_object  :advised_object
-        alias :target_object= :advised_object=
         
-        # Create a join point object. It must have one and only type _or_ object and one method or the special keywords <tt>:all</tt>.
-        # Usage:
-        #  join_point = JoinPoint.new.find :type => ..., :method_name => ... [, (:class_method | :instance_method) => (true | false) ]
-        # where
-        # <tt>:type => type_or_type_name_or_regexp</tt>::
-        #   A single type, type name or regular expression matching only one type. One and only one
-        #   type _or_ object is required. An error is raised otherwise.
-        #
-        # <tt>:method_name => method_name_or_sym</tt>::
-        # <tt>:method => method_name_or_sym</tt>::
-        #   A single method name or symbol. Only one is allowed, although the special flag <tt>:all</tt> is allowed.
-        #
-        # <tt>(:class_method | :instance_method) => (true | false)</tt>::
-        #   Is the method a class or instance method? Defaults to <tt>:instance_method => true</tt>.
-        def initialize options
+        NIL_OBJECT = Aquarium::Utils::NilObject.new
+        
+        def initialize options = {}
           update options
-          assert_valid options
         end
 
         def update options
           options.each do |key, value|
             instance_variable_set "@#{key}", value
           end
+          @advice_kind    ||= Advice::UNKNOWN_ADVICE_KIND
+          @advised_object ||= NIL_OBJECT
+          @parameters     ||= []
         end
-    
+        
         def proceed enclosing_join_point, *args, &block
-          raise ProceedMethodNotAvailable.new("It looks like you tried to call \"JoinPoint#proceed\" (or \"JoinPoint::Context#proceed\") from within advice that isn't \"around\" advice. Only around advice can call proceed. (Specific error: JoinPoint#proceed cannot be called because no \"@proceed_proc\" attribute was set on the corresponding JoinPoint::Context object.)") if @proceed_proc.nil?
-          do_invoke proceed_proc, :call, enclosing_join_point, *args, &block
+          raise ProceedMethodNotAvailable.new("It looks like you tried to call \"JoinPoint#proceed\" (or \"JoinPoint::Context#proceed\") from within advice that isn't \"around\" advice. Only around advice can call proceed. (Specific error: JoinPoint#proceed cannot be invoked because no \"@proceed_proc\" attribute was set on the corresponding JoinPoint::Context object.)") if @proceed_proc.nil?
+          enclosing_join_point.context.parameters = args unless args.nil? or args.empty? 
+          enclosing_join_point.context.block_for_method = block if block 
+          proceed_proc.call enclosing_join_point
         end
         
         def invoke_original_join_point enclosing_join_point, *args, &block
-          do_invoke current_advice_node, :invoke_original_join_point, enclosing_join_point, *args, &block
-        end
-        
-        def do_invoke proc_to_send, method, enclosing_join_point, *args, &block
-          args = parameters if (args.nil? or args.size == 0)
+          raise ContextNotCorrectlyDefined.new("It looks like you tried to call \"JoinPoint#invoke_original_join_point\" (or \"JoinPoint::Context#invoke_original_join_point\") using a join point without a completely formed context object. (Specific error: The original join point cannot be invoked because no \"@current_advice_node\" attribute was set on the corresponding JoinPoint::Context object.)") if @current_advice_node.nil?
+          enclosing_join_point.context.parameters = args unless args.nil? or args.empty? 
           enclosing_join_point.context.block_for_method = block if block 
-          proc_to_send.send method, enclosing_join_point, advised_object, *args
+          current_advice_node.invoke_original_join_point enclosing_join_point
         end
-        protected :do_invoke
         
         alias :to_s :inspect
     
@@ -66,7 +64,7 @@ module Aquarium
           return 1 if other.nil?
           result = self.class <=> other.class 
           return result unless result == 0
-          result = (self.advice_kind.nil? and other.advice_kind.nil?) ? 0 : self.advice_kind <=> other.advice_kind 
+          result = Advice.compare_advice_kinds self.advice_kind, other.advice_kind
           return result unless result == 0
           result = (self.advised_object.object_id.nil? and other.advised_object.object_id.nil?) ? 0 : self.advised_object.object_id <=> other.advised_object.object_id 
           return result unless result == 0
@@ -84,17 +82,10 @@ module Aquarium
         alias :==  :eql?
         alias :=== :eql?
     
-        protected
-    
-        def assert_valid options
-          bad_attributes("Must specify an :advice_kind", options)    unless advice_kind
-          bad_attributes("Must specify an :advised_object", options) unless advised_object
-          bad_attributes("Must specify a :parameters", options)      unless parameters
-        end    
       end
 
-      attr_accessor :target_type, :target_object, :method_name, :visibility, :context
-      attr_reader   :instance_or_class_method
+      attr_accessor :context
+      attr_reader   :target_type, :target_object, :method_name, :visibility, :instance_or_class_method
       
       def instance_method?
         @instance_method
@@ -104,6 +95,23 @@ module Aquarium
         !@instance_method
       end
       
+      # Create a join point object, specifying either one type or one object and a method. 
+      # Only method join points are currently supported by Aquarium.
+      # 
+      # The supported options are
+      # <tt>:type => type | type_name | type_name_regexp</tt>::
+      #   A single type, type name or regular expression matching only one type. One and only one
+      #   type _or_ object is required. An error is raised otherwise.
+      # <tt>:object => object</tt>::
+      #   A single object. One and only one type _or_ object is required. An error is raised otherwise.
+      # <tt>:method_name | :method => method_name_or_symbol</tt>::
+      #   A single method name or symbol. Only one is allowed, although the special flag <tt>:all</tt> 
+      #   is allowed, as long as only one method will be found, subject to the next option.
+      # <tt>:class_method | :instance_method => true | false</tt>::
+      #   Is the method a class or instance method? Defaults to <tt>:instance_method => true</tt>.
+      # 
+      # Note: The range of options is not as rich as for Pointcut, because it is expected that JoinPoint objects
+      # will be explicitly created only rarely by users of Aquarium. Most of the time, Pointcuts will be created.
       def initialize options = {}
         @target_type     = resolve_type options
         @target_object   = options[:object]
@@ -112,9 +120,16 @@ module Aquarium
         @instance_method = options[:instance_method].nil? ? (!class_method) : options[:instance_method]
         @instance_or_class_method  = @instance_method ? :instance : :class
         @visibility = Aquarium::Utils::MethodUtils.visibility(type_or_object, @method_name, class_or_instance_method_flag)
+        @context = options[:context] || JoinPoint::Context.new
         assert_valid options
       end
   
+      def dup
+        jp = super
+        jp.context = @context.dup unless @context.nil?
+        jp
+      end
+      
       def type_or_object
         target_type || target_object
       end
@@ -130,34 +145,23 @@ module Aquarium
         return results.matched.size == 1 ? true : false
       end
       
-      # Invoke the "enclosed" join point, which could be aspect advice wrapping the original runtime join point.
+      # Invoke the join point itself (which could actually be aspect advice wrapping the original join point...).
       # This method can only be called if the join point has a context object defined that represents an actual
       # runtime "state".
       def proceed *args, &block
-        raise ContextNotDefined.new(":proceed can't be called unless the join point has a context object.") if context.nil?
+        raise ContextNotCorrectlyDefined.new(":proceed can't be called unless the join point has a context object.") if context.nil?
         context.proceed self, *args, &block
       end
 
-      # Invoke the actual runtime join point, skipping any intermediate advice.
+      # Invoke the join point itself, skipping any intermediate advice.
       # This method can only be called if the join point has a context object defined that represents an actual
       # runtime "state".
+      # Use this method cautiously, at it could be "surprising" if some advice is not executed!
       def invoke_original_join_point *args, &block
-        raise ContextNotDefined.new(":invoke_original_join_point can't be called unless the join point has a context object.") if context.nil?
+        raise ContextNotCorrectlyDefined.new(":invoke_original_join_point can't be called unless the join point has a context object.") if context.nil?
         context.invoke_original_join_point self, *args, &block
       end
       
-      def make_current_context_join_point context_options
-        new_jp = dup
-        if new_jp.context.nil?
-          new_jp.context = JoinPoint::Context.new context_options
-        else
-          new_jp.context = context.dup
-          new_jp.context.update context_options
-        end
-        new_jp
-      end
-
-      # Needed for comparing this field in #compare_field
       def instance_method
         @instance_method
       end
@@ -238,6 +242,7 @@ module Aquarium
     
       public
   
+      # A "convenience" JoinPoint supporting the "Null Object Pattern."
       NIL_OBJECT = Aquarium::Utils::NilObject.new  
     end
   end

data/lib/aquarium/aspects/pointcut.rb

@@ -26,139 +26,168 @@ module Aquarium
       attr_reader :specification
 
       # Construct a Pointcut for methods in types or objects.
-      #   Pointcut.new :join_points => [...] | :type{s} => [...] | :object{s} => [...] \
-      #      {, :method{s} => [], :method_options => [...], \
+      #   Pointcut.new :join_points => [...] | :type{s} => [...] | :object{s} => [...]
+      #      {, :method{s} => [], :method_options => [...],
       #      :attribute{s} => [...], :attribute_options[...]}
       # where the "{}" indicate optional elements. Most of the arguments have many
       # synonyms, shown below, to promote an English-like DSL.
       #
-      # <tt>:join_points => join_point || [join_point_list]</tt>::
-      # <tt>:join_point  => join_point || [join_point_list]</tt>::
-      # <tt>:for_join_points => join_point || [join_point_list]</tt>::
-      # <tt>:for_join_point  => join_point || [join_point_list]</tt>::
-      # <tt>:on_join_points => join_point || [join_point_list]</tt>::
-      # <tt>:on_join_point  => join_point || [join_point_list]</tt>::
-      # <tt>:within_join_points => join_point || [join_point_list]</tt>::
-      # <tt>:within_join_point  => join_point || [join_point_list]</tt>::
-      #   One or an array of join_points.
+      # The options include the following.
+      # ==== Join Points
+      # Specify one or an array of join_points.
+      # * <tt>:join_points => join_point || [join_point_list]</tt>
+      # * <tt>:join_point  => join_point || [join_point_list]</tt>
+      # * <tt>:for_join_points => join_point || [join_point_list]</tt>
+      # * <tt>:for_join_point  => join_point || [join_point_list]</tt>
+      # * <tt>:on_join_points => join_point || [join_point_list]</tt>
+      # * <tt>:on_join_point  => join_point || [join_point_list]</tt>
+      # * <tt>:within_join_points => join_point || [join_point_list]</tt>
+      # * <tt>:within_join_point  => join_point || [join_point_list]</tt>
       #
-      # <tt>:types => type || [type_list]</tt>::
-      # <tt>:type  => type || [type_list]</tt>::
-      # <tt>:for_types => type || [type_list]</tt>::
-      # <tt>:for_type  => type || [type_list]</tt>::
-      # <tt>:on_types => type || [type_list]</tt>::
-      # <tt>:on_type  => type || [type_list]</tt>::
-      # <tt>:within_types => type || [type_list]</tt>::
-      # <tt>:within_type  => type || [type_list]</tt>::
-      #   One or an array of types, type names and/or type regular expessions to match. 
+      # ===== Types
+      # Specify a type, type name, type name regular expression or an array of the same. (Mixed is allowed.)
+      # * <tt>:types => type || [type_list]</tt>
+      # * <tt>:type  => type || [type_list]</tt>
+      # * <tt>:for_types => type || [type_list]</tt>
+      # * <tt>:for_type  => type || [type_list]</tt>
+      # * <tt>:on_types => type || [type_list]</tt>
+      # * <tt>:on_type  => type || [type_list]</tt>
+      # * <tt>:within_types => type || [type_list]</tt>
+      # * <tt>:within_type  => type || [type_list]</tt>
       #
-      # <tt>:types_and_descendents => type || [type_list]</tt>::
-      # <tt>:type_and_descendents  => type || [type_list]</tt>::
-      # <tt>:types_and_ancestors   => type || [type_list]</tt>::
-      # <tt>:type_and_ancestors    => type || [type_list]</tt>::
-      # <tt>:for_types_and_ancestors   => type || [type_list]</tt>::
-      # <tt>:for_type_and_ancestors    => type || [type_list]</tt>::
-      # <tt>:on_types_and_descendents => type || [type_list]</tt>::
-      # <tt>:on_type_and_descendents  => type || [type_list]</tt>::
-      # <tt>:on_types_and_ancestors   => type || [type_list]</tt>::
-      # <tt>:on_type_and_ancestors    => type || [type_list]</tt>::
-      # <tt>:within_types_and_descendents => type || [type_list]</tt>::
-      # <tt>:within_type_and_descendents  => type || [type_list]</tt>::
-      # <tt>:within_types_and_ancestors   => type || [type_list]</tt>::
-      # <tt>:within_type_and_ancestors    => type || [type_list]</tt>::
-      #   One or an array of types and either their descendents or ancestors. 
-      #   If you want both the descendents _and_ ancestors, use both options.
+      # ===== Types and Ancestors or Descendents
+      # Specify a type, type name, type name regular expression or an array of the same. (Mixed is allowed.)
+      # The ancestors or descendents will also be found. To find <i>both</i> ancestors and descendents, use
+      # both options.
+      # * <tt>:types_and_descendents => type || [type_list]</tt>
+      # * <tt>:type_and_descendents  => type || [type_list]</tt>
+      # * <tt>:types_and_ancestors   => type || [type_list]</tt>
+      # * <tt>:type_and_ancestors    => type || [type_list]</tt>
+      # * <tt>:for_types_and_ancestors   => type || [type_list]</tt>
+      # * <tt>:for_type_and_ancestors    => type || [type_list]</tt>
+      # * <tt>:on_types_and_descendents => type || [type_list]</tt>
+      # * <tt>:on_type_and_descendents  => type || [type_list]</tt>
+      # * <tt>:on_types_and_ancestors   => type || [type_list]</tt>
+      # * <tt>:on_type_and_ancestors    => type || [type_list]</tt>
+      # * <tt>:within_types_and_descendents => type || [type_list]</tt>
+      # * <tt>:within_type_and_descendents  => type || [type_list]</tt>
+      # * <tt>:within_types_and_ancestors   => type || [type_list]</tt>
+      # * <tt>:within_type_and_ancestors    => type || [type_list]</tt>
       #
-      # <tt>:objects => object || [object_list]</tt>::
-      # <tt>:object  => object || [object_list]</tt>::
-      # <tt>:for_objects => object || [object_list]</tt>::
-      # <tt>:for_object  => object || [object_list]</tt>::
-      # <tt>:on_objects => object || [object_list]</tt>::
-      # <tt>:on_object  => object || [object_list]</tt>::
-      # <tt>:within_objects => object || [object_list]</tt>::
-      # <tt>:within_object  => object || [object_list]</tt>::
-      #   Objects to match.
-      #    
-      # <tt>:default_objects => object || [object_list]</tt>::
-      # <tt>:default_object => object || [object_list]</tt>::
-      #   An "internal" flag used by AspectDSL#pointcut when no object or type is specified, 
-      #   the value of :default_objects will be used, if defined. AspectDSL#pointcut sets the 
-      #   value to self, so that the user doesn't have to in the appropriate contexts.
-      #   This flag is subject to change, so don't use it explicitly!
-      #
-      # <tt>:methods => method || [method_list]</tt>::
-      # <tt>:method  => method || [method_list]</tt>::
-      # <tt>:within_methods => method || [method_list]</tt>::
-      # <tt>:within_method  => method || [method_list]</tt>::
-      # <tt>:calling  => method || [method_list]</tt>::
-      # <tt>:calls_to  => method || [method_list]</tt>::
-      # <tt>:invoking  => method || [method_list]</tt>::
-      # <tt>:invocations_of  => method || [method_list]</tt>::
-      # <tt>:sending_message_to  => method || [method_list]</tt>::
-      #   One or an array of methods, method names and/or method regular expessions to match. 
-      #   By default, unless :attributes are specified, searches for public instance methods
-      #   with the method option :exclude_ancestor_methods implied, unless explicit method 
-      #   options are given.
+      # ===== Types and Nested Types
+      # Specify a type, type name, type name regular expression or an array of the same. (Mixed is allowed.)
+      # The nested (enclosed) types will also be found.
+      # * <tt>:types_and_nested_types => type || [type_list]</tt>
+      # * <tt>:type_and_nested_types  => type || [type_list]</tt>
+      # * <tt>:types_and_nested => type || [type_list]</tt>
+      # * <tt>:type_and_nested  => type || [type_list]</tt>
+      # * <tt>:for_types_and_nested_types => type || [type_list]</tt>
+      # * <tt>:for_type_and_nested_types  => type || [type_list]</tt>
+      # * <tt>:for_types_and_nested => type || [type_list]</tt>
+      # * <tt>:for_type_and_nested  => type || [type_list]</tt>
+      # * <tt>:on_types_and_nested_types => type || [type_list]</tt>
+      # * <tt>:on_type_and_nested_types  => type || [type_list]</tt>
+      # * <tt>:on_types_and_nested => type || [type_list]</tt>
+      # * <tt>:on_type_and_nested  => type || [type_list]</tt>
+      # * <tt>:within_types_and_nested_types => type || [type_list]</tt>
+      # * <tt>:within_type_and_nested_types  => type || [type_list]</tt>
+      # * <tt>:within_types_and_nested => type || [type_list]</tt>
+      # * <tt>:within_type_and_nested  => type || [type_list]</tt>
       #
-      # <tt>:method_options => [options]</tt>::
-      #   One or more options supported by Aquarium::Finders::MethodFinder. The :exclude_ancestor_methods
-      #   option is most useful.
+      # ===== Objects
+      # * <tt>:objects => object || [object_list]</tt>
+      # * <tt>:object  => object || [object_list]</tt>
+      # * <tt>:for_objects => object || [object_list]</tt>
+      # * <tt>:for_object  => object || [object_list]</tt>
+      # * <tt>:on_objects => object || [object_list]</tt>
+      # * <tt>:on_object  => object || [object_list]</tt>
+      # * <tt>:within_objects => object || [object_list]</tt>
+      # * <tt>:within_object  => object || [object_list]</tt>
+      #    
+      # ===== "Default" Objects
+      # An "internal" flag used by Aspect::DSL#pointcut. When no object or type is specified 
+      # explicitly, the value of :default_objects will be used, if defined. Aspect::DSL#pointcut
+      # sets the value to +self+, so the user doesn't have to specify a type or object in the
+      # contexts where that would be useful, <i>e.g.,</i> pointcuts defined within a type for join points
+      # within itself. *WARNING*: This flag is subject to change, so don't use it explicitly!
+      # * <tt>:default_objects => object || [object_list]</tt>
+      # * <tt>:default_object => object || [object_list]</tt>
       #
-      # <tt>:reading   => attribute || [attribute_list]</tt>::
-      # <tt>:writing   => attribute || [attribute_list]</tt>::
-      # <tt>:changing => attribute || [attribute_list]</tt>::
-      # <tt>:accessing => attribute || [attribute_list]</tt>::
-      #   One or an array of attribute names and/or regular expessions to match. 
-      #   This is syntactic sugar for the corresponding attribute readers and/or writers
-      #   methods. 
-      #   If <tt>:reading</tt> is specified, just attribute readers are matched.
-      #   If <tt>:writing</tt> is specified, just attribute writers are matched.
-      #   If <tt>:accessing</tt> is specified, both readers and writers are matched.
-      #   Any matches will be joined with the matched <tt>:methods.</tt>.
+      # ===== Methods
+      # A method name, name regular expession or an array of the same. 
+      # By default, if neither <tt>:methods</tt> nor <tt>:attributes</tt> are specified, all public instance methods
+      # will be found, with the method option <tt>:exclude_ancestor_methods</tt> implied, unless explicit method 
+      # options are given.
+      # * <tt>:methods => method || [method_list]</tt>
+      # * <tt>:method  => method || [method_list]</tt>
+      # * <tt>:within_methods => method || [method_list]</tt>
+      # * <tt>:within_method  => method || [method_list]</tt>
+      # * <tt>:calling  => method || [method_list]</tt>
+      # * <tt>:calls_to  => method || [method_list]</tt>
+      # * <tt>:invoking  => method || [method_list]</tt>
+      # * <tt>:invocations_of  => method || [method_list]</tt>
+      # * <tt>:sending_message_to  => method || [method_list]</tt>
       #
-      # <tt>:attributes => attribute || [attribute_list]</tt>::
-      # <tt>:attribute  => attribute || [attribute_list]</tt>::
-      #   One or an array of attribute names and/or regular expessions to match. 
-      #   This is syntactic sugar for the corresponding attribute readers and/or writers
-      #   methods, as specified using the <tt>:attrbute_options</tt>. Any matches will be
-      #   joined with the matched <tt>:methods.</tt>.
+      # ===== Method Options
+      # One or more options supported by Aquarium::Finders::MethodFinder. The <tt>:exclude_ancestor_methods</tt>
+      # option is most useful.
+      # * <tt>:method_options => [options]</tt>
       #
-      # <tt>:attribute_options => [options]</tt>::
-      #   One or more of <tt>:readers</tt>, <tt>:reader</tt> (synonymous), 
-      #   <tt>:writers</tt>, and/or <tt>:writer</tt> (synonymous). By default, both
-      #   readers and writers are matched. 
-      #   <tt>:reading => ...</tt> is synonymous with <tt>:attributes => ..., 
-      #   :attribute_options => [:readers]</tt>.
-      #   <tt>:writing => ...</tt> and <tt>:changing => ...</tt> are synonymous with <tt>:attributes => ..., 
-      #   :attribute_options => [:writers]</tt>.
-      #   <tt>:accessing => ...</tt> is synonymous with <tt>:attributes => ...</tt>.
+      # ===== Attributes
+      # An attribute name, regular expession or array of the same. 
+      # *WARNING* This is syntactic sugar for the corresponding attribute readers and/or writers
+      # methods. The actual attribute accesses are not advised, which can lead to unexpected
+      # behavior. A goal before V1.0 is to support actual attribute accesses, if possible.  
+      # * <tt>:attributes => attribute || [attribute_list]</tt>
+      # * <tt>:attribute  => attribute || [attribute_list]</tt>
+      # * <tt>:reading   => attribute || [attribute_list]</tt>
+      # * <tt>:writing   => attribute || [attribute_list]</tt>
+      # * <tt>:changing => attribute || [attribute_list]</tt>
+      # * <tt>:accessing => attribute || [attribute_list]</tt>
+      # If <tt>:reading</tt> is specified, just attribute readers are matched.
+      # If <tt>:writing</tt> is specified, just attribute writers are matched.
+      # If <tt>:accessing</tt> is specified, both readers and writers are matched.
+      # Any matches will be joined with the matched <tt>:methods.</tt>.
       #
-      # <tt>:exclude_pointcuts   => pc || [pc_list]</tt>::
-      # <tt>:exclude_pointcut    => pc || [pc_list]</tt>::
-      # <tt>:exclude_join_points => jp || [jp_list]</tt>::
-      # <tt>:exclude_join_point  => jp || [jp_list]</tt>::
-      # <tt>:exclude_types       => type || [type_list]</tt>::
-      # <tt>:exclude_types       => type || [type_list]</tt>::
-      # <tt>:exclude_type        => type || [type_list]</tt>::
-      # <tt>:exclude_objects     => object || [object_list]</tt>::
-      # <tt>:exclude_object      => object || [object_list]</tt>::
-      # <tt>:exclude_methods     => method || [method_list]</tt>::
-      # <tt>:exclude_method      => method || [method_list]</tt>::
-      # <tt>:exclude_attributes  => attribute || [attribute_list]</tt>::
-      # <tt>:exclude_attribute   => attribute || [attribute_list]</tt>::
-      #   Also <tt>exclude_{synonyms}</tt> of the same options...
-      #   Exclude the specified "things" from the matched join points. If pointcuts are
-      #   excluded, they should be subsets of the matched pointcuts. Otherwise, the
-      #   resulting pointcut will be empty!
+      # ===== Attribute Options
+      # One or more of <tt>:readers</tt>, <tt>:reader</tt> (synonymous), 
+      # <tt>:writers</tt>, and/or <tt>:writer</tt> (synonymous). By default, both
+      # readers and writers are matched. 
+      # <tt>:reading => ...</tt> is synonymous with <tt>:attributes => ..., 
+      # :attribute_options => [:readers]</tt>.
+      # <tt>:writing => ...</tt> and <tt>:changing => ...</tt> are synonymous with <tt>:attributes => ..., 
+      # :attribute_options => [:writers]</tt>.
+      # <tt>:accessing => ...</tt> is synonymous with <tt>:attributes => ...</tt>.
+      # * <tt>:attribute_options => [options]</tt>
       #
-      # <tt>:exclude_types_and_descendents => type || [type_list]</tt>::
-      # <tt>:exclude_type_and_descendents  => type || [type_list]</tt>::
-      # <tt>:exclude_types_and_ancestors   => type || [type_list]</tt>::
-      # <tt>:exclude_type_and_ancestors    => type || [type_list]</tt>::
-      #   Exclude the specified types and their descendents, ancestors.
-      #   If you want to exclude both the descendents _and_ ancestors, use both options.
+      # ==== Exclusion Options
+      # Exclude the specified "things" from the matched join points. If pointcuts are
+      # excluded, they should be subsets of the matched pointcuts. Otherwise, the
+      # resulting pointcut will be empty!
+      # * <tt>:exclude_pointcuts   => pc || [pc_list]</tt>
+      # * <tt>:exclude_pointcut    => pc || [pc_list]</tt>
+      # * <tt>:exclude_join_points => jp || [jp_list]</tt>
+      # * <tt>:exclude_join_point  => jp || [jp_list]</tt>
+      # * <tt>:exclude_types       => type || [type_list]</tt>
+      # * <tt>:exclude_types       => type || [type_list]</tt>
+      # * <tt>:exclude_type        => type || [type_list]</tt>
+      # * <tt>:exclude_types_and_descendents => type || [type_list]</tt>
+      # * <tt>:exclude_type_and_descendents  => type || [type_list]</tt>
+      # * <tt>:exclude_types_and_ancestors   => type || [type_list]</tt>
+      # * <tt>:exclude_type_and_ancestors    => type || [type_list]</tt>
+      # * <tt>:exclude_types_and_nested_types => type || [type_list]</tt>
+      # * <tt>:exclude_type_and_nested_types  => type || [type_list]</tt>
+      # * <tt>:exclude_types_and_nested       => type || [type_list]</tt>
+      # * <tt>:exclude_type_and_nested        => type || [type_list]</tt>
+      # * <tt>:exclude_objects     => object || [object_list]</tt>
+      # * <tt>:exclude_object      => object || [object_list]</tt>
+      # * <tt>:exclude_methods     => method || [method_list]</tt>
+      # * <tt>:exclude_method      => method || [method_list]</tt>
+      # * <tt>:exclude_attributes  => attribute || [attribute_list]</tt>
+      # * <tt>:exclude_attribute   => attribute || [attribute_list]</tt>
+      # The <tt>exclude_</tt> prefix works with the synonyms of the options shown.
       #
-      # Pointcut.new also accepts all the "universal" options documented in OptionsUtils.
+      # Pointcut.new also accepts all the "universal" options documented in Aquarium::Utils::OptionsUtils.
       def initialize options = {} 
         init_specification options, CANONICAL_OPTIONS, (ATTRIBUTE_OPTIONS_VALUES + Advice::KINDS_IN_PRIORITY_ORDER) do 
           finish_specification_initialization
@@ -231,7 +260,6 @@ module Aquarium
         result
       end
             
-      # TODO remove duplication w/ aspect.rb
       def finish_specification_initialization
         @specification.merge! Pointcut.make_attribute_reading_writing_options(@original_options)
         # Map the method options to their canonical values:
@@ -246,7 +274,7 @@ module Aquarium
       end
 
       def any_type_related_options_given?
-        objects_given? or join_points_given? or types_given? or types_and_descendents_given? or types_and_ancestors_given?
+        objects_given? or join_points_given? or types_given? or types_and_descendents_given? or types_and_ancestors_given? or types_and_nested_types_given?
       end
       
       def self.validate_attribute_options spec_hash, options_hash
@@ -285,9 +313,10 @@ module Aquarium
         finder_options = {}
         exclude_finder_options = {}
         ['', 'exclude_'].each do |prefix|
-          ['', '_and_ancestors', '_and_descendents'].each do |suffix|
-            # Because the user might be asking for descendents and/or ancestors, we convert explicitly-specified
-            # types into names, then "refind" them. While less efficient, it makes the code more uniform.
+          ['', '_and_ancestors', '_and_descendents', '_and_nested_types'].each do |suffix|
+            # Because the user might be asking for descendents, ancestors and/or nested types, we convert
+            # explicitly-specified types into names, then "refind" them. While less efficient, it makes 
+            # the code more uniform.
             eval <<-EOF
               #{prefix}type_regexps_or_names#{suffix} = @specification[:#{prefix}types#{suffix}].map do |t|
                 Aquarium::Utils::TypeUtils.is_type?(t) ? t.name : t