Fix and reword some docstrings again

During I'm reading through the code base to learn MBS, I found out some
typos and minor issues in some other docstrings, and I also found some
docstrings with extra informative description could make it easier to
understand the code.

Signed-off-by: Chenxiong Qi <cqi@redhat.com>

module_build_service/builder/KojiContentGenerator.py

@@ -66,7 +66,6 @@ class KojiContentGenerator(object):
 
     def __init__(self, module, config):
         """
-        :param owner: a string representing who kicked off the builds
         :param module: module_build_service.models.ModuleBuild instance.
         :param config: module_build_service.config.Config instance
         """

module_build_service/builder/KojiModuleBuilder.py

@@ -648,7 +648,7 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules
         Searches for a complete build of an artifact belonging to the module and sets the
         component_build in the MBS database to the found build. This usually returns nothing since
         these builds should *not* exist.
-        :param artifact_name: a ComponentBuild object
+        :param component_build: a ComponentBuild object
         :return: a list of msgs that MBS needs to process
         """
         opts = {'latest': True, 'package': component_build.package, 'inherit': False}
@@ -843,15 +843,19 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules
             self.koji_session.setInheritanceData(tag['id'], inheritance_data)
 
     @module_build_service.utils.validate_koji_tag('dest_tag')
-    def _koji_add_groups_to_tag(self, dest_tag, groups=None):
-        """
-        :param build_tag_name
-        :param groups: A dict {'group' : [package, ...]}
+    def _koji_add_groups_to_tag(self, dest_tag, groups):
+        """Add groups to a tag as well as packages listed by group
+
+        :param dest_tag: the tag groups will be added to. This argument could
+            be a string representing tag name, or a mapping containing tag info
+            which must have name at least.
+        :type dest_tag: str or dict
+        :param dict groups: A dict ``{'group' : [package, ...]}``. If one of
+            the groups has been added to the tag, the group is skipped.
         """
         log.debug("Adding groups=%s to tag=%s" % (list(groups), dest_tag))
         if groups and not isinstance(groups, dict):
             raise ValueError("Expected dict {'group' : [str(package1), ...]")
-
         dest_tag = self._get_tag(dest_tag)['name']
         existing_groups = dict([(p['name'], p['group_id'])
                                 for p
@@ -874,12 +878,15 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules
 
     @module_build_service.utils.validate_koji_tag('tag_name')
     def _koji_create_tag(self, tag_name, arches=None, perm=None):
-        """
-        :param tag_name: name of koji tag
-        :param arches: list of architectures for the tag
-        :param perm: permissions for the tag (used in lock-tag)
+        """Create a tag in Koji
 
         This call is safe to call multiple times.
+
+        :param str tag_name: name of koji tag
+        :kwarg list arches: list of architectures for the tag
+        :kwarg str perm: permissions for the tag (used in lock-tag)
+        :return: a mapping containing raw tag info returned from Koji.
+        :rtype: dict
         """
 
         log.debug("Ensuring existence of tag='%s'." % tag_name)
@@ -936,7 +943,7 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules
         if not tags:
             tags = [self.module_tag, self.module_build_tag]
 
-        # This will help with potential resubmiting of failed builds
+        # This will help with potential resubmitting of failed builds
         pkglists = {}
         for tag in tags:
             pkglists[tag['id']] = dict([(p['package_name'], p['package_id'])
@@ -971,14 +978,21 @@ chmod 644 %buildroot/etc/rpm/macros.zz-modules
 
     @module_build_service.utils.validate_koji_tag(['build_tag', 'dest_tag'])
     def _koji_add_target(self, name, build_tag, dest_tag):
-        """
-        :param name: target name
-        :param build-tag: build_tag name
-        :param dest_tag: dest tag name
+        """Add build target if it doesn't exist or validate the existing one
 
         This call is safe to call multiple times. Raises SystemError() if the existing target
         doesn't match params. The reason not to touch existing target, is that we don't want to
-        accidentaly alter a target which was already used to build some artifacts.
+        accidentally alter a target which was already used to build some artifacts.
+
+        :param str name: target name.
+        :param dict build_tag: build tag info, which must have name at least.
+        :param dict dest_tag: dest tag info, which must have name at least.
+        :return: a mapping containing raw build target info returned from Koji.
+            If a new build target is created, it is the new one. Otherwise,
+            existing build target is returned.
+        :rtype: dict
+        :raises SystemError: if existing build target does not have build_tag
+            name or dest_tag name.
         """
         build_tag = self._get_tag(build_tag)
         dest_tag = self._get_tag(dest_tag)

module_build_service/mmd_resolver.py

@@ -61,7 +61,11 @@ class MMDResolver(object):
 
         See the inline comments for more information.
 
-        :param list deps: List of dicts with dependency name as key and list of streams as value.
+        :param list deps: List of dicts with dependency name as key and list of
+            streams as value. Generally, it is just the return value from
+            ``Modulemd.Dependencies.get_requires`` or
+            ``Modulemd.Dependencies.get_buildrequires`` whose value is
+            converted from ``Modulemd.SimpleSet`` to list.
         :rtype: solv.Dep
         :return: solv.Dep instance with dependencies in form libsolv accepts.
         """

module_build_service/utils/general.py

@@ -95,16 +95,20 @@ def module_build_state_from_msg(msg):
 
 
 def generate_koji_tag(name, stream, version, context, max_length=256):
-    """
-    Generate a koji tag from name, stream, version and context.
+    """Generate a koji tag for a module
 
-    :param name: a module's name
-    :param stream: a module's stream
-    :param version: a module's version
-    :param context: a module's context
-    :kwarg max_length: the maximum length the Koji tag can be before falling back to
-    the old format of "module-<hash>"
+    Generally, a module's koji tag is in format ``module-N-S-V-C``. However, if
+    it is longer than maximum length, old format ``module-hash`` is used.
+
+    :param str name: a module's name
+    :param str stream: a module's stream
+    :param str version: a module's version
+    :param str context: a module's context
+    :kwarg int max_length: the maximum length the Koji tag can be before
+        falling back to the old format of "module-<hash>". Default is 256
+        characters, which is the maximum length of a tag Koji accepts.
     :return: a Koji tag
+    :rtype: str
     """
     nsvc_list = [name, stream, str(version), context]
     nsvc_tag = 'module-' + '-'.join(nsvc_list)

module_build_service/utils/submit.py

@@ -206,6 +206,16 @@ def format_mmd(mmd, scmurl, session=None):
 
 
 def validate_mmd(mmd):
+    """Validate module metadata
+
+    If everything is ok, just keep quiet, otherwise error is raised for
+    specific problem.
+
+    :param mmd: modulemd object representing module metadata.
+    :type mmd: Modulemd.Module
+    :raises Forbidden: if metadata contains module repository but it is not
+        allowed.
+    """
     for modname, mod in mmd.get_module_components().items():
         if mod.get_repository() and not conf.modules_allow_repository:
             raise Forbidden(