docu updated and fixed on some places

also some tab/spaces fixes

6 files changed, 122 insertions, 21 deletions

diff --git a/src/python/openlmi/common/IndicationManager.py b/src/python/openlmi/common/IndicationManager.py
index fe01b70..dbe25f3 100644
--- a/src/python/openlmi/common/IndicationManager.py
+++ b/src/python/openlmi/common/IndicationManager.py
@@ -46,7 +46,7 @@ def enumerate_namespaces(ch):
     first item is a list of object paths of all namespaces in broker and
     the second is a name of namespace, where this information can be found.
 
-    :param ch CIMOM handle.
+    :param ch: CIMOM handle.
     """
     nsclasses = ["CIM_Namespace", "__Namespace"]
     namespaces = ['root/cimv2', 'root/PG_InterOp', 'Interop',
@@ -83,7 +83,7 @@ def find_ns_interop(ch):
     Return name of interop namespace, where ``CIM_IndicationFilter``
     class reside.
 
-    :param ch CIMOM handle.
+    :param ch: CIMOM handle.
     """
     _, ns_interop = enumerate_namespaces(ch)
     return ns_interop
@@ -98,7 +98,7 @@ def parse_filter_name(name):
     """
     Return tuple ``(class_name, filter_id)``.
 
-    :param name (``string``) Value of cim filter's *Name* property.
+    :param name: (``string``) Value of cim filter's *Name* property.
     """
     match = RE_FILTER_NAME.match(name)
     if not match:
@@ -110,7 +110,9 @@ def make_indication_filter_path(class_name, fltr_id, ns_interop):
     """
     Return CIM_IndicationFilter instance path for given filter id.
 
-    :param fltr_id (``string``) Filter name.
+    :param class_name: (``string``) *Scoped class* name.
+    :param fltr_id: (``string``) Filter name.
+    :param ns_interop: (``string``) Interop namespace.
     """
     for arg in ('class_name', 'fltr_id', 'ns_interop'):
         if not isinstance(locals()[arg], basestring):
@@ -131,7 +133,8 @@ def remove_cimom_filter(ch, fltr_path):
 
     Returns list of subscription instace names, that were deleted.
 
-    :param fltr_path (``CIMInstanceName``) Path of ``CIM_IndicationFilter`` to
+    :param ch: CIMOM handle.
+    :param fltr_path: (``CIMInstanceName``) Path of ``CIM_IndicationFilter`` to
         remove.
     """
     if not isinstance(fltr_path, pywbem.CIMInstanceName):
@@ -354,8 +357,8 @@ class IndicationManager(singletonmixin.Singleton):
         """
         Return instance of CIM_IndicationFilter registered in CIMOM if any.
 
-        :param class_name (``string``) *Scoping class* name.
-        :param fltr_id (``string``) Indication name.
+        :param class_name: (``string``) *Scoping class* name.
+        :param fltr_id: (``string``) Indication name.
         """
         ch = self._env.get_cimom_handle()
         cop = make_indication_filter_path(class_name, fltr_id, self.ns_interop)
@@ -372,8 +375,8 @@ class IndicationManager(singletonmixin.Singleton):
         Ensures, that cimom has ``fltr_id`` filter registered as instance.
         If it has, but the query differs it is recreated at broker.
 
-        :param class_name (``string``) *Scoping class* name.
-        :param fltr_id (``string``) Indication name.
+        :param class_name: (``string``) *Scoping class* name.
+        :param fltr_id: (``string``) Indication name.
         """
         inst = self._get_filter_inst(class_name, fltr_id)
         ch = self._env.get_cimom_handle()
@@ -421,7 +424,7 @@ class IndicationManager(singletonmixin.Singleton):
 
         Return a tuple ``(class_name, filter_id, filter_properties)``.
 
-        :param query (``string``) Is filter query.
+        :param query: (``string``) Is filter query.
         """
         if not isinstance(query, basestring):
             raise TypeError("query must be a string")
@@ -438,9 +441,9 @@ class IndicationManager(singletonmixin.Singleton):
         must be registered with this instance before the check can be done.
         Without arguments all registered filters will be checked.
         
-        :param class_name (``string``) Name of *Scoped class* that reduces
+        :param class_name: (``string``) Name of *Scoped class* that reduces
             searched filters.
-        :param fltr_id (``string``) Indication name reducing filters that
+        :param fltr_id: (``string``) Indication name reducing filters that
             will be checked.
         """
         cls_to_check = self._filters.keys()
@@ -494,7 +497,7 @@ class IndicationManager(singletonmixin.Singleton):
             ``property_name -> value``, where at least ``Query`` property
             must be set. ``Name`` property will be automatically created
             as 'LMI:<class_name>:<filter_id>'.
-        :param ensure_installed (``bool``) Whether to check for filter presence
+        :param ensure_installed: (``bool``) Whether to check for filter presence
             at broker and install them if missing. **Note** That in order
             for this to work, the context must be updated with user's
             credentials. See :ref:`update_context-label`.
@@ -643,6 +646,7 @@ class IndicationManager(singletonmixin.Singleton):
         """
         Return True, if there is someone subscribed for given filter.
 
+        :param class_name: (``string``) *Scoping class* name.
         :param fltr_id: (``string``) ID of the filter to check.
         """
         with self._access_lock:
@@ -657,6 +661,7 @@ class IndicationManager(singletonmixin.Singleton):
         """
         Return True, if filter id has been registered with current instance.
 
+        :param class_name: (``string``) *Scoping class* name.
         :param fltr_id: (``string``) ID of the filter to check.
         """
         with self._access_lock:
diff --git a/src/software/openlmi/software/LMI_InstalledSoftwareIdentity.py b/src/software/openlmi/software/LMI_InstalledSoftwareIdentity.py
index 811298c..82c2049 100644
--- a/src/software/openlmi/software/LMI_InstalledSoftwareIdentity.py
+++ b/src/software/openlmi/software/LMI_InstalledSoftwareIdentity.py
@@ -107,10 +107,10 @@ class LMI_InstalledSoftwareIdentity(CIMProvider2):
                     "Expected object path for InstalledSoftware!")
 
         model["System"] = model.path["System"] = ComputerSystem.get_path()
-	pkg_info = Identity.object_path2pkg(
-	    model['InstalledSoftware'], kind='installed')
-	model['InstalledSoftware'] = Identity.pkg2model(pkg_info)
-	return model
+        pkg_info = Identity.object_path2pkg(
+            model['InstalledSoftware'], kind='installed')
+        model['InstalledSoftware'] = Identity.pkg2model(pkg_info)
+        return model
 
     @cmpi_logging.trace_method
     def enum_instances(self, env, model, keys_only):
diff --git a/src/software/openlmi/software/cimom_entry.py b/src/software/openlmi/software/cimom_entry.py
index 4aa1d44..6c37c9a 100644
--- a/src/software/openlmi/software/cimom_entry.py
+++ b/src/software/openlmi/software/cimom_entry.py
@@ -101,9 +101,13 @@ def get_providers(env):
     return providers
 
 def can_unload(_env):
-    """ Says, whether providers can be unlouded. """
+    """
+    Says, whether providers can be unloaded.
+    """
     return True
 
 def shutdown(_env):
-    """ Release resources upon cleanup. """
+    """
+    Release resources upon cleanup.
+    """
     YumDB.get_instance().clean_up()
diff --git a/src/software/openlmi/software/yumdb/__init__.py b/src/software/openlmi/software/yumdb/__init__.py
index 5f6f7c3..c992608 100644
--- a/src/software/openlmi/software/yumdb/__init__.py
+++ b/src/software/openlmi/software/yumdb/__init__.py
@@ -59,7 +59,7 @@ from openlmi.software.util import get_signal_name
 # be possibly killed) and is respawned in case it's dead.
 MAX_JOB_WAIT_TIME = 30
 
-# this may be used as an argument to YumWorker
+# this may be used as an argument to YumWorker to setup logging
 YUM_WORKER_DEBUG_LOGGING_CONFIG = {
     "version" : 1,
     "formatters": {
@@ -590,35 +590,75 @@ class YumDB(singletonmixin.Singleton):
     # *************************************************************************
     @job_request()
     def get_job(self, jobid):
+        """
+        Return instance of ``YumJob`` with given ``jobid``.
+        """
         return self._do_job(jobs.YumJobGet(jobid))
 
     @job_request()
     def get_job_list(self):
+        """
+        Return list of all asynchronous jobs.
+        """
         return self._do_job(jobs.YumJobGetList())
 
     @job_request()
     def get_job_by_name(self, name):
+        """
+        Return asynchronous job filtered by its name.
+        """
         return self._do_job(jobs.YumJobGetByName(name))
 
     @job_request()
     def set_job_priority(self, jobid, priority):
+        """
+        Change priority of asynchronous job. This will change
+        its order in queue, if it is still enqeueued.
+
+        Return object of job.
+        """
         return self._do_job(jobs.YumJobSetPriority(jobid, priority))
 
     @job_request()
     def update_job(self, jobid, **kwargs):
+        """
+        Update metadata of job.
+
+        :param kwargs: (``dict``) Is a dictionary of job's property names
+            with mapped new values. Only keys given will be changed in
+            desired job.
+
+            **Note** that only keys, that do not affect job's priority or its
+            scheduling for deletion can be changed. See :ref:`YumJobUpdate`.
+        """
         return self._do_job(jobs.YumJobUpdate(jobid, **kwargs))
 
     @job_request()
     def reschedule_job(self, jobid,
             delete_on_completion, time_before_removal):
+        """
+        Change the scheduling of job for deletion.
+
+        :param delete_on_completion: (``bool``) Says, whether the job will
+            be scheduled for deletion at ``finished + time_before_removal``
+            time.
+        :param time_before_removal: (``int``) Number of seconds, after the job
+            is finished, it will be kept alive.
+        """
         return self._do_job(jobs.YumJobReschedule(jobid,
             delete_on_completion, time_before_removal))
 
     @job_request()
     def delete_job(self, jobid):
+        """
+        Delete job object. This can be called only on finished job.
+        """
         return self._do_job(jobs.YumJobDelete(jobid))
 
     @job_request()
     def terminate_job(self, jobid):
+        """
+        Terminate job. This can be called only on *NEW* job.
+        """
         return self._do_job(jobs.YumJobTerminate(jobid))
 
diff --git a/src/software/openlmi/software/yumdb/jobs.py b/src/software/openlmi/software/yumdb/jobs.py
index a46a2ca..84fd3ed 100644
--- a/src/software/openlmi/software/yumdb/jobs.py
+++ b/src/software/openlmi/software/yumdb/jobs.py
@@ -293,7 +293,14 @@ class YumJobSetPriority(YumJobOnJob): #pylint: disable=R0903
         self.new_priority = priority
 
 class YumJobUpdate(YumJobOnJob):      #pylint: disable=R0903
-    """Update job's metadata."""
+    """
+    .. _YumJobUpdate:
+
+    Update job's metadata. There are some forbidden properties, that
+    can not be changed in this way. Those are all affecting job's priority
+    and its scheduling for deletion. Plus any that store job's state.
+    All forbidden properties are listed in ``FORBIDDEN_PROPERTIES``.
+    """
     __slots__ = ('data', )
     FORBIDDEN_PROPERTIES = (
         'async', 'jobid', 'created', 'started', 'priority', 'finished',
diff --git a/src/software/openlmi/software/yumdb/util.py b/src/software/openlmi/software/yumdb/util.py
index f2af151..bd2a0ca 100644
--- a/src/software/openlmi/software/yumdb/util.py
+++ b/src/software/openlmi/software/yumdb/util.py
@@ -1,3 +1,28 @@
+# Software Management Providers
+#
+# Copyright (C) 2012-2013 Red Hat, Inc.  All rights reserved.
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+#
+# Authors: Michal Minar <miminar@redhat.com>
+#
+
+"""
+Common utilities meant to be used only be ``yumdb`` subpackage.
+"""
+
 from itertools import chain
 import inspect
 import logging
@@ -6,7 +31,18 @@ import os
 from openlmi.software.yumdb import errors
 
 class DispatchingFormatter:
+    """
+    Formatter class for logging module. It allows to predefine different
+    format string for paricular module names.
+    """
     def __init__(self, formatters, default):
+        """
+        *format* in parameters description can be either ``string`` or
+        another formatter object.
+
+        :param formatters (``dict``) Mapping of module names to *format*.
+        :param default Default *format*.
+        """
         for k, formatter in formatters.items():
             if isinstance(formatter, basestring):
                 formatters[k] = logging.Formatter(formatter)
@@ -16,6 +52,9 @@ class DispatchingFormatter:
         self._default_formatter = default
 
     def format(self, record):
+        """
+        Interface for logging module.
+        """
         formatter = self._formatters.get(record.name, self._default_formatter)
         return formatter.format(record)
 
@@ -89,6 +128,12 @@ def trace_function(func):
     return _wrapper
 
 def setup_logging(config):
+    """
+    This is meant to be used by ``YumWorker`` process to setup logging
+    independent of what providers are using. Unfortunately ``YumWorker``
+    can not use the same facilities as the rest of program, because
+    logging is done through *broker*.
+    """
     try:
         logging.config.dictConfig(config)
     except Exception:   #pylint: disable=W0703