lib/krikri/entity_behavior.rb in krikri-0.12.0 vs lib/krikri/entity_behavior.rb in krikri-0.12.1

@@ -1,40 +1,86 @@
 
 module Krikri
   ##
-  # Base class for behaviors related to entities that are generated or revised
-  # by activities.
+  # Base class for retrieval behaviors related to entities that were generated 
+  # or revised by a `Krikri::Activity`.
   #
-  # A SoftwareAgent implements #entity_behavior, which returns an appropriate
-  # subclass of EntityBehavior.  When an Activity is queried for its entities,
-  # it instantiates an instance of its particular SoftwareAgent, and then
-  # calls the #entities method of the agent's entity behavior.
+  # @example implementing an entity behavior
+  #   class CustomBehavior < Krikri::EntityBehavior
+  #     def entities(load = true, include_invalidated = false)
+  #       activity_uris(include_invalidated) do |uri|
+  #         # some behavior over URIs to return initialized entities
+  #       end
+  #     end
+  #   end
   #
+  # @example retrieving entities with a behavior
+  #   Krikri::Activity.find(activity_id)
+  #   CustomBehavor.entities(activity)
+  #
+  # A `SoftwareAgent` implements `#entity_behavior`, which returns an appropriate
+  # subclass of `EntityBehavior`.  When an Activity is queried for its entities,
+  # it instantiates an instance of its particular `SoftwareAgent`, and then
+  # calls the `#entities` method of the agent's entity behavior.
+  #
   # @see Krikri::Activity#entities
   # @see lib/krikri/entity_behaviors
-  #
   class EntityBehavior
+    # @!attribute [r] activity
+    #   @return [Krikri::Activity]
     attr_reader :activity
+
+    ##
+    # @param activity [Krikri::Activity]
     def initialize(activity)
       @activity = activity
     end
 
     ##
     # Return an Enumerator of objects that have been affected by our @activity.
     #
-    # @return [Enumerator] objects
+    # @param load [Boolean] `true` to force load the entities from the datastore
+    #   on access
+    # @param include_invalidated [Boolean] `true` to include entities marked as
+    #   invalid.
+    #
+    # @return [Enumerator] the entities. When possible, they should be 
+    #   initialized & retrieved lazily.
+    #   
+    #
     # @see lib/krikri/entity_behaviors
     # @see Krikri::Activity#entities
     #
+    # @see Krikri::LDP::Invalidatable for more about "invalidated" entities
     def entities(*args)
-      raise NotImplementedError 
+      raise NotImplementedError
     end
 
     ##
-    # @see Krikri::Activity#entities
-    # @see Krikri::EntityBehavior#entities
+    # Initializes an instance of this class with the given `Activity` and
+    # returns an enumerator of the associated entities.
     #
+    # @param activity   [Krikri::Activity]
+    # @param load                [Boolean]
+    # @param include_invalidated [Boolean]
+    #
+    # @see Krikri::EntityBehavior#entities
+    # @see Krikri::Activity#entities
     def self.entities(activity, *args)
       new(activity).entities(*args)
+    end
+
+    private
+    
+    ##
+    # Private utility method capturing common logic for applying entity logic to
+    # uris gathered from the instance's `Krikri::Activity`.
+    #
+    # @param include_invalided [Boolean]
+    #
+    # @return [Enumerator::Lazy] the uris, lazily mapped to the behavior in the
+    #   given block
+    def activity_uris(include_invalidated, &block)
+      activity.entity_uris(include_invalidated).lazy.map(&block)
     end
   end
 end