updated doc comments for cimom callbacks

cimom callbacks for filter enablement have misleading param names and
miss proper doc

2 files changed, 114 insertions, 9 deletions

diff --git a/src/python/openlmi/common/IndicationManager.py b/src/python/openlmi/common/IndicationManager.py
index 7834378..a17703f 100644
--- a/src/python/openlmi/common/IndicationManager.py
+++ b/src/python/openlmi/common/IndicationManager.py
@@ -512,10 +512,19 @@ class IndicationManager(singletonmixin.Singleton):
                 self.ensure_filters_installed(class_name=class_name)
 
     @cmpi_logging.trace_method
-    def authorize_filter(self, _env, fltr, _ns, _classes, _owner):
+    def authorize_filter(self, _env, fltr, _class_name, _op, _owner):
         """
         AuthorizeFilter callback from CIMOM. Call this method from appropriate
-        CIMOM callback.
+        CIMOM callback
+
+        It asks us to verify whether this filter is allowed.
+
+        :param fltr: Contains the filter that must be authorized. 
+        :param _class_name: (``String``) Contains the class name extracted
+            from the filter FROM clause. 
+        :param _op: The name of the class for which monitoring is required.
+            Only the namespace part is set if className is a process indication.
+        :param _owner The owner argument is the destination owner. 
         """
         with self._access_lock:
             res = self._get_matching_filter(fltr)
@@ -527,10 +536,24 @@ class IndicationManager(singletonmixin.Singleton):
             return False
 
     @cmpi_logging.trace_method
-    def activate_filter(self, _env, fltr, _ns, _classes, first_activation):
+    def activate_filter(self, _env, fltr, _class_name, _class_path,
+            first_activation):
         """
         ActivateFilter callback from CIMOM. Call this method from appropriate
         CIMOM callback.
+
+        It ask us to begin monitoring a resource. The function shall begin
+        monitoring the resource according to the filter express only.
+
+        :param fltr: The filter argument contains the filter specification
+            for this subscription to become active. 
+        :param _class_name: (``String``) The class name extracted from the filter
+            FROM clause. 
+        :param _class_path: (``CIMInstanceName``) The name of the class for
+            which monitoring is required. Only the namespace part is set if
+            eventType is a process indication. 
+        :param first_activation: (``bool``) Set to true if this is the first
+            filter for className. 
         """
         with self._access_lock:
             if not first_activation:
@@ -542,10 +565,23 @@ class IndicationManager(singletonmixin.Singleton):
                         make_filter_name(res[0], res[1]), fltr)
 
     @cmpi_logging.trace_method
-    def deactivate_filter(self, _env, fltr, _ns, _classes, last_activation):
+    def deactivate_filter(self, _env, fltr, _class_name, _class_path,
+            last_activation):
         """
         DeactivateFilter callback from CIMOM. Call this method from appropriate
         CIMOM callback.
+
+        Informs us that monitoring using this filter should stop.
+
+        :param fltr: The filter argument contains the filter specification for
+            this subscription to become active. 
+        :param class_name: (``String``) The class name extracted from the filter
+            FROM clause. 
+        :param class_path: (``CIMInstanceName``) class_path The name of the
+            class for which monitoring is required. Only the namespace part is
+            set if className is a process indication. 
+        :last_activation: (``bool``) Set to true if this is the last filter for
+            className. 
         """
         with self._access_lock:
             if not last_activation:
@@ -561,6 +597,11 @@ class IndicationManager(singletonmixin.Singleton):
         """
         EnableIndications callback from CIMOM. Call this method from
         appropriate CIMOM callback.
+
+        Tells us that indications can now be generated. The MB is now prepared
+        to process indications. The function is normally called by the MB after
+        having done its intialization and processing of persistent subscription
+        requests.
         """
         with self._access_lock:
             self._enabled = True
@@ -571,6 +612,11 @@ class IndicationManager(singletonmixin.Singleton):
         """
         EnableIndications callback from CIMOM. Call this method from
         appropriate CIMOM callback.
+
+        Tells us that we should stop generating indications. MB will not accept
+        any indications until enabled again. The function is normally called
+        when the MB is shutting down indication services either temporarily or
+        permanently.
         """
         with self._access_lock:
             self._enabled = False
@@ -604,7 +650,8 @@ class IndicationManager(singletonmixin.Singleton):
         ind['SourceInstance'] = instance
         ind['SourceInstanceHost'] = socket.gethostname()
         ind['SourceInstanceModelPath'] = str(instance.path)
-        ind['IndicationFilterName'] = make_filter_name(instance.classname, filter_id)
+        ind['IndicationFilterName'] = make_filter_name(
+                instance.classname, filter_id)
         ind['PerceivedSeverity'] = self.SEVERITY_INFO
 
         cmpi_logging.logger.info("Sending indication %s for %s" %
diff --git a/src/software/openlmi/software/cimom_entry.py b/src/software/openlmi/software/cimom_entry.py
index d507a01..70df071 100644
--- a/src/software/openlmi/software/cimom_entry.py
+++ b/src/software/openlmi/software/cimom_entry.py
@@ -118,22 +118,80 @@ def get_providers(env):
 
     return providers
 
-def authorize_filter(env, fltr, ns, classes, owner):
+def authorize_filter(env, fltr, class_name, op, owner):
+    """
+    CIMOM callback.
+
+    It asks us to verify whether this filter is allowed.
+
+    :param fltr: (``String``) Contains the filter that must be authorized. 
+    :param class_name: (``String``) Contains the class name extracted
+        from the filter FROM clause. 
+    :param op: The name of the class for which monitoring is required.
+        Only the namespace part is set if className is a process indication.
+    :param owner The owner argument is the destination owner. 
+    """
     IndicationManager.get_instance().authorize_filter(
-            env, fltr, ns, classes, owner)
+            env, fltr, class_name, op, owner)
 
-def activate_filter (env, fltr, ns, classes, first_activation):
+def activate_filter(env, fltr, class_name, class_path, first_activation):
+    """
+    CIMOM callback.
+    
+    It ask us to begin monitoring a resource. The function shall begin
+    monitoring the resource according to the filter express only.
+
+    :param fltr: (``String``) The filter argument contains the filter
+        specification for this subscription to become active. 
+    :param class_name: (``String``) The class name extracted from the filter
+        FROM clause. 
+    :param class_path: (``CIMInstanceName``) The name of the class for which
+        monitoring is required. Only the namespace part is set if eventType
+        is a process indication. 
+    :param first_activation: (``bool``) Set to true if this is the first
+        filter for className. 
+    """
     IndicationManager.get_instance().activate_filter(
             env, fltr, class_name, class_path, first_activation)
 
-def deactivate_filter(env, fltr, ns, classes, last_activation):
+def deactivate_filter(env, fltr, class_name, class_path, last_activation):
+    """
+    CIMOM callback.
+
+    Informs us that monitoring using this filter should stop.
+
+    :param fltr: (``String``) The filter argument contains the filter
+        specification for this subscription to become active. 
+    :param class_name: (``String``) The class name extracted from the filter
+        FROM clause. 
+    :param class_path: (``CIMInstanceName``) class_path The name of the class
+        for which monitoring is required. Only the namespace part is set
+        if className is a process indication. 
+    :last_activation: (``bool``) Set to true if this is the last filter for
+        className. 
+    """
     IndicationManager.get_instance().deactivate_filter(
             env, fltr, class_name, class_path, last_activation)
 
 def enable_indications(env):
+    """
+    CIMOM callback.
+
+    Tells us that indications can now be generated. The MB is now prepared
+    to process indications. The function is normally called by the MB after
+    having done its intialization and processing of persistent subscription
+    requests.
+    """
     IndicationManager.get_instance().enable_indications(env)
 
 def disable_indications(env):
+    """
+    CIMOM callback.
+
+    Tells us that we should stop generating indications. MB will not accept any
+    indications until enabled again. The function is normally called when the
+    MB is shutting down indication services either temporarily or permanently.
+    """
     IndicationManager.get_instance().disable_indications(env)
 
 def can_unload(_env):