patriarch 0.2.3 → 0.2.4

data/README.md

@@ -17,7 +17,9 @@ and keep track of all this in one transaction.
 Patriarch allows you to handle all of this in a matter of seconds and 
 - gathers all of the redis calls in one transaction object that stores a redis queue ready to be processed
 - rollbacks SQL destroy transaction if redis database dropped while processing the instruction queue to clean data relative
-to SQL rows destroyed. Reduces possibilities of painful database incoherences
+to SQL rows destroyed. Reduces possibilities of painful database incoherence.
+
+Note : We use Patriarch in production
 
 # What Patriarch is not 
 
@@ -26,8 +28,14 @@ Patriarch is not a replacement for SQL
 ## Installation
 
 Add this line to your application's Gemfile:
+```ruby
+gem 'patriarch'
+```
 
-    gem 'patriarch'
+Or this one if you want to be up-to-date in real time
+```ruby
+gem 'patriarch', :git => 'https://github.com/nateware/redis-objects.git'
+```
 
 And then execute:
 
@@ -40,11 +48,11 @@ Or install it yourself as:
 ## Usage
 
 First include it into your model:
-
-    class User < ActiveRecord::Base
-      include Patriarch::Behaviours
-    end
-
+```ruby
+class User < ActiveRecord::Base
+  include Patriarch::Behaviours
+end
+```
 ### Initializing files for a behaviour
 
 Just type in: 
@@ -55,10 +63,168 @@ Just type in:
 
 Add a behaviour in a simple way and write this just below the include:
 
-    add_behaviour :on => [Model1,Model2] # add active_behaviour performed on instances of model1, model2
-    add_behaviour :by => [Model3]        # add passive_behaviour performed on us by instances of model3
+```ruby
+add_behaviour :behaviour, :on => [:model1,:model2] # add active_behaviour performed on instances of model1, model2
+add_behaviour :behaviour, :by => :model3           # add passive_behaviour performed on us by instances of model3
+```
 
 It works like belongs_to and has_many helpers of active record, you need to include declarations in both models
+Let's say we have a Users that we want it to be able to like instances from model Post and Message. You may want to use
+aliases like did below with as and undo_as options
+```ruby
+class User < ActiveRecord::Base
+  include Patriarch::Behaviours
+  add_behaviour :like, :on => [:notification,:post], :as => :love, :undo_as => :hate
+end
+
+class Post < ActiveRecord::Base
+  include Patriarch::Behaviours
+  add_behaviour :like, :by => :user
+end
+
+class Message < ActiveRecord::Base
+  include Patriarch::Behaviours
+  add_behaviour :like, :by => :user
+end
+```
+This will provide 'behaviour' methods and tool methods whose name are built like this :
+```ruby
+"#{actor_model_name.pluralize}_#{behaviour_in_progressive_present_form}_me" # tool method to retrieve models that acted on me
+"#{target_model_name.pluralize}_i_#{behaviour}"                             # tool method to retrieve models i acted on
+```
+Adding suffix ids will prevent costly model instantiations and requesting the database and only return ids as an array
+of Fixnum
+
+And now with the example ...
+```ruby
+# Let's grab an user a message and a post, we assume some are already created
+user = User.first
+post = Post.first
+mess = Message.find(10)
+
+user.like post
+user.love mess
+
+user.posts_i_like        # => [post]
+user.messages_i_like     # => [mess]
+user.posts_i_love        # => [post]
+
+user.posts_i_like_ids    # => [1]
+useu.messages_i_like_ids # => [10]
+useu.messages_i_love_ids # => [10]
+
+post.users_loving_me     # => [user]
+mess.users_liking_me_ids # => [1]
+
+user.undo_like mess
+user.messages_i_like     # => []
+user.messages_i_like_ids # => []
+
+user.hate post
+user.posts_i_like     # => []
+user.posts_i_love_ids # => []
+```
+### Tripartite relations
+
+You can also define tripartite behaviours. An example we use is that you can comment a post via a message.
+Tripartite behaviours implies that a medium is used to perform an action.
+For our little example that would become : 
+
+```ruby
+class User < ActiveRecord::Base
+  include Patriarch::Behaviours
+  add_behaviour :comment, :on => :post, :via => :message
+end
+
+class Post < ActiveRecord::Base
+  include Patriarch::Behaviours
+  add_behaviour :comment, :by => :user, :via => :message
+end
+
+class Message < ActiveRecord::Base
+  include Patriarch::Behaviours
+  add_behaviour :comment, :medium_between => [:user,:post]
+end
+```
+
+This will provide 'behaviour' methods and tool methods whose name are built like this :
+```ruby
+"#{actor_model_name.pluralize}_#{behaviour_in_progressive_present_form}_me_via_#{medium_model_name.pluralize}" 
+# tool method to retrieve models that acted on me through medium
+
+"#{target_model_name.pluralize}_i_#{behaviour}_via_#{medium_model_name.pluralize}"                             
+# tool method to retrieve models i acted on me through medium
+
+"#{actor_model_name.pluralize}_#{behaviour_in_progressive_present_form}_#{target_model_name.pluralize}_via_me"
+# tool method to retrieve models that acted through me on target
+```
+
+Adding suffix ids will prevent costly model instantiations and requesting the database and only return ids as an array
+of Fixnum. See Options section to learn more about some detailed job.
+
+And now with the example ...
+```ruby
+# Let's grab an user a message and a post, we assume some are already created
+user = User.first
+post = Post.first
+mess = Message.first
+
+user.comment mess,post
+
+user.posts_i_comment_via_messages       # => [post]
+user.posts_i_comment_via_messages_ids   # => [1]
+
+post.users_commenting_me_via_messages     # => [user]
+post.users_commenting_me_via_messages_ids # => [1]
+
+mess.users_commenting_posts_via_me      
+# => [{:actor_type => User, :actor_id => 1, :medium_type => Message, :medium_id => 1, :target_type => Post, :target_id => 1}]  
+
+user.undo_like mess
+user.messages_i_like     # => []
+user.messages_i_like_ids # => []
+
+user.hate post
+user.posts_i_like     # => []
+user.posts_i_love_ids # => []
+```
+
+Also, aliases work for tripartite the same way they do for bipartite 
+
+### Options
+#### with_scores
+Patriarch automatically stores interactions with a score that equals to Time.now.to_f. This is for the moment not possible
+to change this and is a behaviour of Patriarch that one should be able to change in a near future.
+You can hence passe the options :with_scores => true when calling tool methods
+
+```ruby
+# Let's grab an user a message and a post, we assume some are already created
+user = User.first
+post = Post.first
+
+user.like post
+
+user.posts_i_like                            # => [post]
+user.posts_i_like :with_scores => true       # => [[post,123456.789123]]
+```
+#### with_medium
+Patriarch allows you to bring back the entire "who's who" information of a tripartite transaction
+It will bring something like that if you take back the example we gave a while ago
+
+```ruby
+user = User.first
+post = Post.first
+mess = Message.first
+
+user.comment mess,post
+
+user.posts_i_comment_via_messages       # => [post]
+user.posts_i_comment_via_messages_ids   # => [1]
+user.posts_i_comment_via_messages_ids :with_medium => true
+# => [{:actor_type => User, :actor_id => 1, :medium_type => Message, :medium_id => 1, :target_type => Post, :target_id => 1}]  
+```
+
+"with_medium" option is not compatible with "with_scores" option
 
 ## Contributing
 
@@ -67,3 +233,8 @@ It works like belongs_to and has_many helpers of active record, you need to incl
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+## Thanks
+
+Thanks for using this gem ! If you are really really grateful or want to talk about this and happen to be in Paris, you
+can issue a beer pull request that i will happily merge.

data/lib/generators/patriarch/templates/manager_service-tripartite.rb

@@ -33,4 +33,13 @@ class Patriarch::Services::<%= class_name %>::ManagerService < Patriarch::Manage
     # If everything went smoothly
     transac.execute if (transac_first_step && callbacks_were_completed)
   end
-end
+
+  def resolve_with_reduced_sql_database_calls(actor_class,actor_id,target_class,target_id,medium_class,medium_id)
+    actor = OpenStruct.new ; actor.id = actor_id  
+    actor.define_singleton_method(:class) do  
+      actor_class
+    end
+    target = OpenStruct.new ; target.id = target_id ; target.class = target_class
+    medium = OpenStruct.new ; medium.id = medium_id ; medium.class = medium_class
+  end
+end

data/lib/patriarch/authorization_service.rb

@@ -1,21 +1,30 @@
 require 'singleton'
 
+# Mother class of all the Patriarch::__behaviour__::AuthorizationService
+# We use singleton pattern here
 module Patriarch
+  class ForbiddenBehaviourException < Exception; end
+
   class AuthorizationService
     include Singleton
 
-    # override if necessary
+    # All authorization services are called by method #grant
+    # Since type verification is an eternal we implement grant in the mother class and let daughter classes
+    # call it with super and benefit from verify_types or bypass it completely and override the function
     def grant?(transac)
-      # Insert authorization logic here ...    
-      if verify_types(transac)
+      if check_types(transac)
         true
       else
-        raise "that behaviour is not authorized"
+        raise Patriarch::ForbiddenBehaviourException, "that behaviour is not authorized"
       end
-      #true
     end
 
-    def verify_types(transac)
+    # When declaring behaviours in model thanks to add_behaviour helper we enforce that ONLY the behaviour declared
+    # are authorized. We hence verify that when a behaviour is called.
+    # For example User could be able to like Items and thus be blessed with #like as an instance method.
+    # But then we can tell any user instance to like any object, this method denies these behaviours.
+    # @transac [Patriarch::Transaction] the transaction to be authorized (or not)
+    def check_types(transac)
       actor_model       = transac.actor.class
       actor_model_sym   = actor_model.name.underscore.to_sym 
 
@@ -29,19 +38,21 @@ module Patriarch
       auths = []
 
       if transac.tripartite?
-        # Verif for actor
+        # Verification for actor
         auths << actor_model.patriarch_behaviours[behaviour][:on].map{ |b_sym| b_sym.to_s.underscore.to_sym }.include?(target_model_sym)
         auths << actor_model.patriarch_behaviours[behaviour][:via].map{ |b_sym| b_sym.to_s.underscore.to_sym }.include?(medium_model_sym)      
 
-        # Verif for target
+        # Verification for target
         auths << target_model.patriarch_behaviours[behaviour][:by].map{ |b_sym| b_sym.to_s.underscore.to_sym }.include?(actor_model_sym)
         auths << target_model.patriarch_behaviours[behaviour][:via].map{ |b_sym| b_sym.to_s.underscore.to_sym }.include?(medium_model_sym) 
 
-        # Verif for medium
-        auths << medium_model.patriarch_behaviours[behaviour][:medium_between].map{ |dual_sym_tab| dual_sym_tab.map{ |b_sym| b_sym.to_s.underscore.to_sym } }.include?( 
-          [actor_model_sym, target_model_sym]
-        )
-        # cas particulier
+        # Verification for medium
+        # Pay attention here since add_behaviour syntax is different when being a medium
+        auths << medium_model.patriarch_behaviours[behaviour][:medium_between].map do |dual_sym_tab| 
+            dual_sym_tab.map{ |b_sym| b_sym.to_s.underscore.to_sym } 
+          end.include?( 
+            [actor_model_sym, target_model_sym] 
+          )
       else
         auths << actor_model.patriarch_behaviours[behaviour][:on].map{ |b_sym| b_sym.to_s.underscore.to_sym }.include?(target_model_sym)
         auths << target_model.patriarch_behaviours[behaviour][:by].map{ |b_sym| b_sym.to_s.underscore.to_sym }.include?(actor_model_sym)             

data/lib/patriarch/behaviours.rb

@@ -20,13 +20,17 @@ module Patriarch
     class << self
 
       # Helper function to complete the anonymous module we include later in the process in the enhanced model class
-      def complete_custom_active_module_bipartite(module_to_complete,relation_type,acted_on_model_list,options={})
-        module_to_complete.class_eval do
+      # @param [Module] anon_module refers to the anonymous module to be completed
+      # @param [String] behaviour the behaviour for which we complete the module with tools method
+      # @param [Array] acted_on_model_list the list of model classes that i can target with the behaviour
+      # @param [Hash] options options can serve to build custom alias for tool methods
+      def complete_custom_active_module_bipartite(anon_module,behaviour,acted_on_model_list,options={})
+        anon_module.class_eval do
 
           acted_on_model_list.each do |acted_on_model|
 
             # Compute names based on conventions
-            classic_tool_method_name = "#{acted_on_model.to_s.tableize}_i_#{relation_type.to_s}"
+            classic_tool_method_name = "#{acted_on_model.to_s.tableize}_i_#{behaviour}"
             raw_tool_method_name = classic_tool_method_name + "_ids"
             redis_key = "patriarch_" + classic_tool_method_name
 
@@ -37,29 +41,35 @@ module Patriarch
                 get_models_from_ids(self,acted_on_model.to_s.classify.constantize,raw_tool_method_name,options)
             end
             if options[:as]
-              alias_for_classic = classic_tool_method_name.sub(relation_type.to_s, options[:as].to_s)
-              alias_method alias_for_classic, classic_tool_method_name 
-            end 
+              alias_for_classic = classic_tool_method_name.sub(behaviour, options[:as].to_s)
+              alias_method alias_for_classic, classic_tool_method_name
+            end
 
             define_method(raw_tool_method_name) do |options={}|
-              Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options)              
+              Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options)
             end
             if options[:as]
-              alias_for_raw = raw_tool_method_name.sub(relation_type.to_s, options[:as].to_s)
+              alias_for_raw = raw_tool_method_name.sub(behaviour, options[:as].to_s)
               alias_method alias_for_raw, raw_tool_method_name
-            end             
+            end
           end
         end
       end
 
-      def complete_custom_passive_module_bipartite(module_to_complete,relation_type,targetted_by_model_list,options={})
-        module_to_complete.class_eval do
 
-          targetted_by_model_list.each do |targetted_by_model|
+       # Helper function to complete the anonymous module we include later in the process in the enhanced model class
+      # @param [Module] anon_module refers to the anonymous module to be completed
+      # @param [String] behaviour the behaviour for which we complete the module with tools method
+      # @param [Array] targeted_by_model_list the list of model classes that can target me with the behaviour
+      # @param [Hash] options options can serve to build custom alias for tool methods
+      def complete_custom_passive_module_bipartite(anon_module,behaviour,targeted_by_model_list,options={})
+        anon_module.class_eval do
+
+          targeted_by_model_list.each do |targeted_by_model|
 
-            # Compute names based on conventions    
-            progressive_present_relation_type = (Verbs::Conjugator.conjugate relation_type.to_sym, :aspect => :progressive).split(/ /).last
-            classic_tool_method_name = "#{targetted_by_model.to_s.tableize}_#{progressive_present_relation_type}_me"
+            # Compute names based on conventions
+            progressive_present_relation_type = (Verbs::Conjugator.conjugate behaviour.to_sym, :aspect => :progressive).split(/ /).last
+            classic_tool_method_name = "#{targeted_by_model.to_s.tableize}_#{progressive_present_relation_type}_me"
             raw_tool_method_name = classic_tool_method_name + "_ids"
             redis_key = "patriarch_" + classic_tool_method_name
 
@@ -67,43 +77,49 @@ module Patriarch
             # Redis key has the same radical as the method in class by convention (but has a patriarch_ prefix to avoid collisions with other gems)
             define_method(classic_tool_method_name) do |options={}|
               Patriarch::ToolServices::RedisExtractorService.instance.
-                get_models_from_ids(self,targetted_by_model.to_s.classify.constantize,raw_tool_method_name,options)
+                get_models_from_ids(self,targeted_by_model.to_s.classify.constantize,raw_tool_method_name,options)
             end
             if options[:as]
-              progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last              
+              progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last
               alias_for_classic = classic_tool_method_name.sub(progressive_present_relation_type,progressive_present_relation_type_alias)
               alias_method alias_for_classic,  classic_tool_method_name
             end
 
             define_method(raw_tool_method_name) do |options={}|
-              Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options)              
+              Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options)
             end
             if options[:as]
-              progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last              
+              progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last
               alias_for_raw = raw_tool_method_name.sub(progressive_present_relation_type,progressive_present_relation_type_alias)
               alias_method alias_for_raw,  raw_tool_method_name
-            end            
+            end
 
           end
 
         end
-      end      
+      end
 
-      def complete_custom_active_module_tripartite(module_to_complete,relation_type,acted_on_model_list,via_model_list,options={})
-        module_to_complete.class_eval do
+      # Helper function to complete the anonymous module we include later in the process in the enhanced model class
+      # @param [Module] anon_module refers to the anonymous module to be completed
+      # @param [String] behaviour the behaviour for which we complete the module with tools method
+      # @param [Array] acted_on_model_list the list of model classes that i can target with the behaviour
+      # @param [Array] via_model_list the list of model classes that the behaviour use to act through
+      # @param [Hash] options options can serve to build custom alias for tool methods
+      def complete_custom_active_module_tripartite(anon_module,behaviour,acted_on_model_list,via_model_list,options={})
+        anon_module.class_eval do
 
           acted_on_model_list.each do |acted_on_model|
             via_model_list.each do |via_model|
 
               # Compute names based on conventions
               # fallen_angels_i_praise_via_love_letters
-              target_classic_tool_method_name = "#{acted_on_model.to_s.tableize}_i_#{relation_type.to_s}_via_#{via_model.to_s.tableize}"
+              target_classic_tool_method_name = "#{acted_on_model.to_s.tableize}_i_#{behaviour}_via_#{via_model.to_s.tableize}"
               target_raw_tool_method_name = target_classic_tool_method_name + "_ids"
 
               # love_letters_i_use_to_praise_fallen_angels
-              medium_classic_tool_method_name = "#{via_model.to_s.tableize}_i_use_to_#{relation_type.to_s}_#{acted_on_model.to_s.tableize}"
-              medium_raw_tool_method_name = medium_classic_tool_method_name + "_ids"              
-              
+              medium_classic_tool_method_name = "#{via_model.to_s.tableize}_i_use_to_#{behaviour}_#{acted_on_model.to_s.tableize}"
+              medium_raw_tool_method_name = medium_classic_tool_method_name + "_ids"
+
               redis_key = "patriarch_" + target_classic_tool_method_name
 
               # Define methods with the pattern : items_i_like that returns models and items_i_like_ids that return
@@ -113,17 +129,17 @@ module Patriarch
                   get_models_from_ids(self,acted_on_model.to_s.classify.constantize,target_raw_tool_method_name,options.merge({:tripartite => true}))
               end
               if options[:as]
-                alias_for_classic = target_classic_tool_method_name.sub(relation_type.to_s, options[:as].to_s)
-                alias_method alias_for_classic, target_classic_tool_method_name 
-              end 
+                alias_for_classic = target_classic_tool_method_name.sub(behaviour, options[:as].to_s)
+                alias_method alias_for_classic, target_classic_tool_method_name
+              end
 
               define_method(target_raw_tool_method_name) do |options={}|
                 Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options.merge({:tripartite => true, :protagonist_type  => :target}))
               end
               if options[:as]
-                alias_for_target_raw = target_raw_tool_method_name.sub(relation_type.to_s, options[:as].to_s)
+                alias_for_target_raw = target_raw_tool_method_name.sub(behaviour, options[:as].to_s)
                 alias_method alias_for_target_raw, target_raw_tool_method_name
-              end                    
+              end
 
               #
               define_method(medium_classic_tool_method_name) do |options={}|
@@ -131,48 +147,54 @@ module Patriarch
                   get_models_from_ids(self,via_model.to_s.classify.constantize,medium_raw_tool_method_name,options.merge({:tripartite => true}))
               end
               if options[:as]
-                alias_for_medium_classic = medium_classic_tool_method_name.sub(relation_type.to_s, options[:as].to_s)
-                alias_method alias_for_medium_classic, medium_classic_tool_method_name 
-              end 
+                alias_for_medium_classic = medium_classic_tool_method_name.sub(behaviour, options[:as].to_s)
+                alias_method alias_for_medium_classic, medium_classic_tool_method_name
+              end
               #
 
               define_method(medium_raw_tool_method_name) do |options={}|
                 Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options.merge({:tripartite => true, :protagonist_type  => :medium}))
               end
               if options[:as]
-                alias_for_medium_raw = medium_raw_tool_method_name.sub(relation_type.to_s, options[:as].to_s)
+                alias_for_medium_raw = medium_raw_tool_method_name.sub(behaviour, options[:as].to_s)
                 alias_method alias_for_medium_raw, medium_raw_tool_method_name
-              end                
+              end
 
             end
           end
 
-        end        
+        end
       end
 
-      def complete_custom_passive_module_tripartite(module_to_complete,relation_type,targetted_by_model_list,via_model_list,options={})
-        module_to_complete.class_eval do
-
-          targetted_by_model_list.each do |targetted_by_model|
+      # Helper function to complete the anonymous module we include later in the process in the enhanced model class
+      # @param [Module] anon_module refers to the anonymous module to be completed
+      # @param [String] behaviour the behaviour for which we complete the module with tools method
+      # @param [Array] targeted_by_model_list the list of model classes that can target me with the behaviour
+      # @param [Array] via_model_list the list of model classes that the behaviour use to act through
+      # @param [Hash] options options can serve to build custom alias for tool methods
+      def complete_custom_passive_module_tripartite(anon_module,behaviour,targeted_by_model_list,via_model_list,options={})
+        anon_module.class_eval do
+
+          targeted_by_model_list.each do |targeted_by_model|
             via_model_list.each do |via_model|
-              # Compute names based on conventions    
-              progressive_present_relation_type = (Verbs::Conjugator.conjugate relation_type.to_sym, :aspect => :progressive).split(/ /).last
-              
-              actor_classic_tool_method_name  = "#{targetted_by_model.to_s.tableize}_#{progressive_present_relation_type}_me_via_#{via_model.to_s.tableize}"
+              # Compute names based on conventions
+              progressive_present_relation_type = (Verbs::Conjugator.conjugate behaviour.to_sym, :aspect => :progressive).split(/ /).last
+
+              actor_classic_tool_method_name  = "#{targeted_by_model.to_s.tableize}_#{progressive_present_relation_type}_me_via_#{via_model.to_s.tableize}"
               actor_raw_tool_method_name      = actor_classic_tool_method_name + "_ids"
-              
+
               #"love_letters_used_by_monsters_to_praise_me"
-              medium_classic_tool_method_name = "#{via_model.to_s.tableize}_used_by_#{targetted_by_model.to_s.tableize}_to_#{relation_type.to_s}_me"
+              medium_classic_tool_method_name = "#{via_model.to_s.tableize}_used_by_#{targeted_by_model.to_s.tableize}_to_#{behaviour}_me"
               medium_raw_tool_method_name     = medium_classic_tool_method_name + "_ids"
-              
+
               redis_key = "patriarch_" + actor_classic_tool_method_name
 
               define_method(actor_classic_tool_method_name) do |options={}|
                 Patriarch::ToolServices::RedisExtractorService.instance.
-                  get_models_from_ids(self,targetted_by_model.to_s.classify.constantize,actor_raw_tool_method_name,options.merge({:tripartite => true}))
+                  get_models_from_ids(self,targeted_by_model.to_s.classify.constantize,actor_raw_tool_method_name,options.merge({:tripartite => true}))
               end
               if options[:as]
-                progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last              
+                progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last
                 alias_for_actor_classic = actor_classic_tool_method_name.sub(progressive_present_relation_type,progressive_present_relation_type_alias)
                 alias_method alias_for_actor_classic,  actor_classic_tool_method_name
               end
@@ -181,36 +203,41 @@ module Patriarch
                 Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options.merge({:tripartite => true , :protagonist_type  => :actor}))
               end
               if options[:as]
-                progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last              
+                progressive_present_relation_type_alias = (Verbs::Conjugator.conjugate options[:as], :aspect => :progressive).split(/ /).last
                 alias_for_actor_raw = actor_raw_tool_method_name.sub(progressive_present_relation_type,progressive_present_relation_type_alias)
                 alias_method alias_for_actor_raw,  actor_raw_tool_method_name
-              end        
+              end
 
               define_method(medium_classic_tool_method_name) do |options={}|
                 Patriarch::ToolServices::RedisExtractorService.instance.
                   get_models_from_ids(self,via_model.to_s.classify.constantize,medium_raw_tool_method_name,options.merge({:tripartite => true}))
-              end   
+              end
               #TODO add alias there
               # FIXME id in it is wrong ...
               define_method(medium_raw_tool_method_name) do |options={}|
                 Patriarch::ToolServices::RedisExtractorService.instance.get_ids_from_sorted_set(self,redis_key,options.merge({:tripartite => true , :protagonist_type  => :medium}))
-              end            
+              end
 
             end
           end
 
         end
-      end       
+      end
 
+      #:nodoc:
       def included(klass)
+        # Classic extend of ClassMethods module embedded within this module
         klass.extend ClassMethods
-        #klass.extend ActiveModel::Callbacks
         unless klass.respond_to?(:before_destroy) && klass.respond_to?(:after_destroy)
           raise AddBehaviourDependencyError, "class #{klass.name} including Patriarch::Behaviours does not support callbacks"
         end
 
+        # insert callback logic here : behaviours have to be cleaned when a destroy occur in SQL
+        # First we build the transaction with #compute_redis_dependencies
+        # We execute the clean only when the SQL transaction commit to avoid data inconsistency if a SQL Rollback occurs
+        # in a middle of a cascading transaction
         klass.class_eval do
-          
+
           before_destroy :compute_redis_dependencies
           def compute_redis_dependencies
             @redis_destroy_transac_object = Patriarch::ToolServices::RedisCleanerService.instance.clean_all(self)
@@ -240,40 +267,47 @@ module Patriarch
       end
     end
 
+    # Gathers class methods that should be available for model that include Patriarch::Behaviours
     module ClassMethods
 
-      def check_add_behaviour_syntax(behaviour,options)
+
+      # Helper that checks if options syntax is correct
+      # Raises errors if not with indications on what should be corrected
+      # @param [Object] options
+      def check_add_behaviour_syntax(options)
         if options[:medium_between] || options[:via]
-          check_tripartite_add_behaviour_syntax(behaviour,options)
+          check_tripartite_add_behaviour_syntax(options)
         elsif options[:on] || options[:by]
-          check_bipartite_add_behaviour_syntax(behaviour,options)
+          check_bipartite_add_behaviour_syntax(options)
         end
       end
 
-      def check_bipartite_add_behaviour_syntax(behaviour,options)
+      #:nodoc:
+      def check_bipartite_add_behaviour_syntax(options)
         # Either you add a behaviour on another model or allow a behaviour on you by another model
         unless options[:by].nil? ^ options[:on].nil?
           raise AddBehaviourSyntaxError, "you must not define a behaviour as active (using on) and passive at the same time (using by)"
         end
-      
-        # as option should be a string or symbol 
+
+        # as option should be a string or symbol
         if options[:as]
-          unless [Symbol,String].include?(options[:as].class) 
+          unless [Symbol,String].include?(options[:as].class)
             raise AddBehaviourSyntaxError, "as option should be a string or symbol"
-          end        
+          end
         end
-      end        
+      end
 
-      def check_tripartite_add_behaviour_syntax(behaviour,options)
+      #:nodoc:
+      def check_tripartite_add_behaviour_syntax(options)
         # Xor on options :medium_between and :via, disparate cases ...
         unless options[:medium_between].nil? ^ options[:via].nil?
           raise AddBehaviourSyntaxError, "you must not define a behaviour as active (using on) and passive at the same time (using by)"
-        end        
+        end
 
         if options[:via]
           unless options[:by].nil? ^ options[:on].nil?
             raise AddBehaviourSyntaxError, "you must not define a behaviour as active (using on) and passive at the same time (using by)"
-          end        
+          end
         else
           medium_between_option = options[:medium_between]
           unless medium_between_option.is_a?(Array) && medium_between_option.size == 2
@@ -282,8 +316,8 @@ module Patriarch
         end
 
         if options[:as]
-          # as option should be a string or symbol 
-          unless [Symbol,String].include?(options[:as].class) 
+          # as option should be a string or symbol
+          unless [Symbol,String].include?(options[:as].class)
             raise AddBehaviourSyntaxError, "as option should be a string or symbol"
           end
         end
@@ -299,7 +333,11 @@ module Patriarch
         end
       end
 
-      def add_aliases_for_functionnalities(module_to_complete,behaviour,options)
+      # @param [Module] module_to_complete
+      # @param [String] behaviour
+      # @param [Object] options
+      # Adds alias for behaviour calls available to models if options allow to do so
+      def add_aliases_for_functionality(module_to_complete,behaviour,options)
         if options[:as]
           behaviour_alias = options[:as].to_s
         end
@@ -308,25 +346,30 @@ module Patriarch
           behaviour_undo_alias = options[:undo_as].to_s
         end
 
-        if options[:on] 
+        if options[:on]
           module_to_complete.instance_eval do
             # add behaviour_alias
-            if options[:as]            
+            if options[:as]
               alias_method behaviour_alias, behaviour
             end
 
             # add undo_behaviour_alias
-            if options[:undo_as]            
+            if options[:undo_as]
               alias_method behaviour_undo_alias, Patriarch.undo(behaviour)
-            end              
+            end
           end
-        end              
+        end
       end
 
-      def add_functionnalities_for_bipartite(module_to_complete,behaviour,options)
-        module_to_complete.instance_eval do
+      # @param [Module] anon_module
+      # @param [String] behaviour
+      # Add basic behaviours calls to models in bipartite situations
+      def add_functionality_for_bipartite(anon_module,behaviour)
+        anon_module.instance_eval do
 
           instance_eval do
+            # in instance_eval situations, there is no scope change so if we want to define included as a "self" method
+            # we are obliged to use this
             (class << self; self; end).send(:define_method,:included) do |klass|
               klass.extend ActiveModel::Callbacks
               klass.send(:define_model_callbacks, behaviour, Patriarch.undo(behaviour))
@@ -336,24 +379,29 @@ module Patriarch
           # behave
           define_method(behaviour) do |entity,options={}|
             run_callbacks behaviour do
-              "Patriarch::Services::#{behaviour.classify}::ManagerService".constantize.instance.resolve(self,entity,options)   
+              "Patriarch::Services::#{behaviour.classify}::ManagerService".constantize.instance.resolve(self,entity,options)
             end
           end
 
           # undo_behave
           define_method(Patriarch.undo(behaviour).to_sym) do |entity,options={}|
             run_callbacks Patriarch.undo(behaviour).to_sym do
-              "Patriarch::Services::#{(Patriarch.undo(behaviour)).classify}::ManagerService".constantize.instance.resolve(self,entity,options)   
+              "Patriarch::Services::#{(Patriarch.undo(behaviour)).classify}::ManagerService".constantize.instance.resolve(self,entity,options)
             end
           end
 
         end # instance_eval
       end
 
-      def add_functionnalities_for_tripartite(module_to_complete,behaviour,options)
-        module_to_complete.instance_eval do
+      # @param [Module] anon_module
+      # @param [String] behaviour
+      # Add basic behaviours calls to models in tripartite situations
+      def add_functionality_for_tripartite(anon_module,behaviour)
+        anon_module.instance_eval do
 
           instance_eval do
+            # in instance_eval situations, there is no scope change so if we want to define included as a "self" method
+            # we are obliged to use this
             (class << self; self; end).send(:define_method,:included) do |klass|
               klass.extend ActiveModel::Callbacks
               klass.send(:define_model_callbacks, behaviour, Patriarch.undo(behaviour))
@@ -363,7 +411,7 @@ module Patriarch
           # behave
           define_method(behaviour) do |via_entity,entity,options={}|
             run_callbacks behaviour.to_sym do
-              "Patriarch::Services::#{behaviour.classify}::ManagerService".constantize.instance.resolve(self,entity,via_entity,options)   
+              "Patriarch::Services::#{behaviour.classify}::ManagerService".constantize.instance.resolve(self,entity,via_entity,options)
             end
           end
 
@@ -371,48 +419,56 @@ module Patriarch
           # undo_behave
           define_method(Patriarch.undo(behaviour)) do |via_entity,entity,options={}|
             run_callbacks Patriarch.undo(behaviour).to_sym do
-              "Patriarch::Services::#{Patriarch.undo(behaviour).classify}::ManagerService".constantize.instance.resolve(self,entity,via_entity,options)   
+              "Patriarch::Services::#{Patriarch.undo(behaviour).classify}::ManagerService".constantize.instance.resolve(self,entity,via_entity,options)
             end
           end
 
         end # instance_eval
       end
 
+      # @param [String] behaviour
+      # @param [Hash] options
+      # Registers at a class level a declaration of bipartite behaviour so that it can be used
+      # to check protagonist types when calling behaviours
       def register_bipartite_behaviour(behaviour,options)
+        behaviour = behaviour.underscore.to_sym
+
         self.patriarch_behaviours ||= { }
         #self.patriarch_behaviours[behaviour.underscore.to_sym] ||= { :on => [], :by =>[] }
-        self.patriarch_behaviours[behaviour.underscore.to_sym] ||= { }
-        self.patriarch_behaviours[behaviour.underscore.to_sym][:on] ||= []
-        self.patriarch_behaviours[behaviour.underscore.to_sym][:by] ||= []         
-
-        if options[:on] 
-          self.patriarch_behaviours[behaviour.underscore.to_sym][:on] << options[:on]
-          self.patriarch_behaviours[behaviour.underscore.to_sym][:on].uniq!
-          self.patriarch_behaviours[behaviour.underscore.to_sym][:on].flatten!
+        self.patriarch_behaviours[behaviour] ||= { }
+        self.patriarch_behaviours[behaviour][:on] ||= []
+        self.patriarch_behaviours[behaviour][:by] ||= []
+
+        if options[:on]
+          self.patriarch_behaviours[behaviour][:on] << options[:on]
+          self.patriarch_behaviours[behaviour][:on].uniq!
+          self.patriarch_behaviours[behaviour][:on].flatten!
         elsif options[:by]
-          self.patriarch_behaviours[behaviour.underscore.to_sym][:by] << options[:by]
-          self.patriarch_behaviours[behaviour.underscore.to_sym][:by].uniq!
-          self.patriarch_behaviours[behaviour.underscore.to_sym][:by].flatten!
-        end 
+          self.patriarch_behaviours[behaviour][:by] << options[:by]
+          self.patriarch_behaviours[behaviour][:by].uniq!
+          self.patriarch_behaviours[behaviour][:by].flatten!
+        end
       end
 
+      # @param [String] behaviour
+      # @param [Hash] options
+      # Registers at a class level a declaration of tripartite behaviour so that it can be used
+      # to check protagonist types when calling behaviours
       def register_tripartite_behaviour(behaviour,options)
-        # TODO disjonction register tripartite
-        # register the behaviour we just added
         behaviour = behaviour.underscore.to_sym
 
         self.patriarch_behaviours ||= { }
-        self.patriarch_behaviours[behaviour]  ||= {}             
-        
+        self.patriarch_behaviours[behaviour]  ||= {}
+
         if options[:via]
           #self.patriarch_behaviours[behaviour.underscore.to_sym] ||= { :on => [], :by => [], :via => [] }
           self.patriarch_behaviours[behaviour][:on] ||= []
-          self.patriarch_behaviours[behaviour][:by] ||= [] 
-          self.patriarch_behaviours[behaviour][:via] ||= [] 
+          self.patriarch_behaviours[behaviour][:by] ||= []
+          self.patriarch_behaviours[behaviour][:via] ||= []
         elsif options[:medium_between]
           #self.patriarch_behaviours[behaviour.underscore.to_sym] ||= { :medium_between => [] }
-          self.patriarch_behaviours[behaviour][:medium_between] ||= []          
-        end 
+          self.patriarch_behaviours[behaviour][:medium_between] ||= []
+        end
 
         if options[:via]
           if options[:on]
@@ -426,35 +482,38 @@ module Patriarch
           end
             self.patriarch_behaviours[behaviour][:via] << options[:via]
             self.patriarch_behaviours[behaviour][:via].uniq!
-            self.patriarch_behaviours[behaviour][:via].flatten!    
+            self.patriarch_behaviours[behaviour][:via].flatten!
         elsif options[:medium_between]
           self.patriarch_behaviours[behaviour][:medium_between] << options[:medium_between]
           self.patriarch_behaviours[behaviour][:medium_between].uniq!
           self.patriarch_behaviours[behaviour][:medium_between]
-        end    
+        end
       end
 
+      # @param [Symbol] behaviour the tripartite behaviour we want to add to our model
+      # @param [Object] options information useful to determine if supplementary functionality such as aliases or custom
+      # tool method shall be implemented
       def add_tripartite_behaviour(behaviour,options)
         behaviour = behaviour.to_s.underscore
 
-        check_add_behaviour_syntax(behaviour,options)
+        check_add_behaviour_syntax(options)
 
         methods_mod = Module.new do; end
 
         # Target on Actor cases
         if options[:via]
           # Actor case
-          if options[:on]    
-            add_functionnalities_for_tripartite(methods_mod,behaviour,options)            
-            add_aliases_for_functionnalities(methods_mod,behaviour,options)   
+          if options[:on]
+            add_functionality_for_tripartite(methods_mod,behaviour)
+            add_aliases_for_functionality(methods_mod,behaviour,options)
             acted_on_model_list = Array(options[:on])
             via_model_list = Array(options[:via])
-            Patriarch::Behaviours.complete_custom_active_module_tripartite(methods_mod,behaviour,acted_on_model_list,via_model_list,options)            
+            Patriarch::Behaviours.complete_custom_active_module_tripartite(methods_mod,behaviour,acted_on_model_list,via_model_list,options)
             #Target case
           elsif options[:by]
-            targetted_by_model_list = Array(options[:by])          
-            via_model_list = Array(options[:via])                      
-            Patriarch::Behaviours.complete_custom_passive_module_tripartite(methods_mod,behaviour,targetted_by_model_list,via_model_list,options)
+            targeted_by_model_list = Array(options[:by])
+            via_model_list = Array(options[:via])
+            Patriarch::Behaviours.complete_custom_passive_module_tripartite(methods_mod,behaviour,targeted_by_model_list,via_model_list,options)
           end
         # Medium case
         elsif options[:medium_between]
@@ -463,35 +522,38 @@ module Patriarch
 
         # Finally ...
         include methods_mod
-        # include in which we can overwite the methods of the previous custom module included there ...
+        # include in which we can override the methods of the previous custom module included there ...
         include "Patriarch::Behaviours::#{behaviour.classify}::ToolsMethods".constantize
         # register behaviour we just added
-        register_tripartite_behaviour(behaviour,options)        
+        register_tripartite_behaviour(behaviour,options)
       end
 
+      # @param [Symbol] behaviour the bipartite behaviour we want to add to our model
+      # @param [Object] options information useful to determine if supplementary functionality such as aliases or custom
+      # tool method shall be implemented
       def add_bipartite_behaviour(behaviour,options)
-        # add_behaviour :like, :by => bla,  :on => [:item,:user] || :community, :as => :aimer, :reverse_as => :haïr ...
-        
+        # add_behaviour :like, :by => bla,  :on => [:item,:user] || :community, :as => :love, :reverse_as => :hate ...
+
         behaviour = behaviour.to_s.underscore
 
-        check_add_behaviour_syntax(behaviour,options)
+        check_add_behaviour_syntax(options)
 
         methods_mod = Module.new do; end
 
-        if options[:on] 
+        if options[:on]
           # Adds active methods and defines the hook to set callbacks on them
-          add_functionnalities_for_bipartite(methods_mod,behaviour,options)
-          add_aliases_for_functionnalities(methods_mod,behaviour,options)  
+          add_functionality_for_bipartite(methods_mod,behaviour)
+          add_aliases_for_functionality(methods_mod,behaviour,options)
           acted_on_model_list = Array(options[:on])
-          Patriarch::Behaviours.complete_custom_active_module_bipartite(methods_mod,behaviour,acted_on_model_list,options)                  
+          Patriarch::Behaviours.complete_custom_active_module_bipartite(methods_mod,behaviour,acted_on_model_list,options)
         else
-          targetted_by_model_list = Array(options[:by])          
-          Patriarch::Behaviours.complete_custom_passive_module_bipartite(methods_mod,behaviour,targetted_by_model_list,options)
+          targeted_by_model_list = Array(options[:by])
+          Patriarch::Behaviours.complete_custom_passive_module_bipartite(methods_mod,behaviour,targeted_by_model_list,options)
         end
 
         # Finally includes the custom module
         include methods_mod
-        # include in which we can overwite the methods of the previous custom module included there ...
+        # include in which we can override the methods of the previous custom module included there ...
         include "Patriarch::Behaviours::#{behaviour.classify}::ToolsMethods".constantize
         # register the behaviour we just added
         register_bipartite_behaviour(behaviour,options)