[DOC] Updated doc and comments

bzr revid: tde@openerp.com-20120403154941-0h83ws1av3clhxg4

doc/api/need_action_specs.rst

@@ -13,7 +13,7 @@ This class wraps a class (ir.needaction_users) that behaves like a many2many fie
 Objects using the need_action feature should override the ``get_needaction_user_ids`` method. This methods returns a dictionary whose keys are record ids, and values a list of user ids, like in a many2many relationship. Therefore by defining only one method, you can specify if an action is required by defining the users that have to do it, in every possible situation.
 
 This class also offers several global services,:
- - ``needaction_get_record_ids``: for a given model_name and uid, get all record ids that ask this user to perform an action. This mechanism is used for instance to display the number of pending actions in menus, such as Leads (12)
+ - ``needaction_get_record_ids``: for the current model and uid, get all record ids that ask this user to perform an action. This mechanism is used for instance to display the number of pending actions in menus, such as Leads (12)
  - ``needaction_get_action_count``: as ``needaction_get_record_ids`` but returns only the number of action, not the ids (performs a search with count=True)
  - ``needaction_get_user_record_references``: for a given uid, get all the records that ask this user to perform an action. Records are given as references, a list of tuples (model_name, record_id)
 
@@ -25,7 +25,7 @@ This revision adds three functional fields to ``ir.ui.menu`` model :
  - ``needaction_uid_ctr``: integer field. If the target model uses the need action mechanism, this field gives the number of actions the current user has to perform.
  - ``needaction_record_ids``: many2many field. If the target model uses the need action mechanism, this field holds the ids of the record requesting the user to perform an action.
 
-Those fields are functional, because they must be recalculated for each user, and each time menus are displayed. ``needaction_uid_ctr`` takes into account the domain of the action, in order to display accurate numbers.
+Those fields are functional, because they depend on the user and must therefore be computed at every refresh, each time menus are displayed. The use of the need action mechanism is done by taking into account the action domain in order to display accurate results. When computing the value of the functional fields, the ids of records asking the user to perform an action is concatenated to the action domain. A counting search is then performed on the model, giving back the number of action the users has to perform, limited to the domain of the action.
 
 Addon implementation example
 ++++++++++++++++++++++++++++

openerp/addons/base/ir/ir_needaction.py

@@ -83,7 +83,7 @@ class ir_needaction_users(osv.osv):
         return True
 
 
-class ir_needaction(osv.osv):
+class ir_needaction_mixin(osv.osv):
     '''Mixin class for objects using the need action feature.
     
     Need action feature can be used by objects willing to be able to
@@ -106,7 +106,7 @@ class ir_needaction(osv.osv):
     that have to do it, in every possible situation.
     
     This class also offers several global services,:
-    - ``needaction_get_record_ids``: for a given model_name and uid, get
+    - ``needaction_get_record_ids``: for the current model and uid, get
       all record ids that ask this user to perform an action. This
       mechanism is used for instance to display the number of pending
       actions in menus, such as Leads (12)
@@ -117,7 +117,7 @@ class ir_needaction(osv.osv):
       the records that ask this user to perform an action. Records
       are given as references, a list of tuples (model_name, record_id)
     '''
-    _name = 'ir.needaction'
+    _name = 'ir.ir_needaction_mixin'
     _description = 'Need action of users on records API'
     
     #------------------------------------------------------
@@ -125,6 +125,9 @@ class ir_needaction(osv.osv):
     #------------------------------------------------------
     
     def get_needaction_user_ids(self, cr, uid, ids, context=None):
+        """ Returns the user_ids that have to perform an action
+            :return: dict { record_id: [user_ids], }
+        """
         return dict.fromkeys(ids, [])
     
     def create(self, cr, uid, values, context=None):