Fixed our docstring lint errors

9 files changed, 41 insertions, 22 deletions

diff --git a/pylint/checkers/base.py b/pylint/checkers/base.py
index e6aecf21a..0f8991145 100644
--- a/pylint/checkers/base.py
+++ b/pylint/checkers/base.py
@@ -166,8 +166,12 @@ def _determine_function_name_type(node, config=None):
     """Determine the name type whose regex the a function's name should match.
 
     :param node: A function node.
+    :type node: astroid.node_classes.NodeNG
     :param config: Configuration from which to pull additional property classes.
+    :type config: :class:`optparse.Values`
+
     :returns: One of ('function', 'method', 'attr')
+    :rtype: str
     """
     property_classes, property_names = _get_properties(config)
     if not node.is_method():
diff --git a/pylint/checkers/format.py b/pylint/checkers/format.py
index d03ec2707..91535b46d 100644
--- a/pylint/checkers/format.py
+++ b/pylint/checkers/format.py
@@ -233,8 +233,12 @@ def _Offsets(*args):
 def _BeforeBlockOffsets(single, with_body):
     """Valid alternative indent offsets for continued lines before blocks.
 
-    :param single: Valid offset for statements on a single logical line.
-    :param with_body: Valid offset for statements on several lines.
+    :param int single: Valid offset for statements on a single logical line.
+    :param int with_body: Valid offset for statements on several lines.
+
+    :returns: A dictionary mapping indent offsets to a string representing
+        whether the indent if for a line or block.
+    :rtype: dict
     """
     return {single: SINGLE_LINE, with_body: WITH_BODY}
 
@@ -390,8 +394,8 @@ class ContinuedLineState(object):
         push_token relies on the caller to filter out those
         interesting tokens.
 
-        :param token: The concrete token
-        :param position: The position of the token in the stream.
+        :param int token: The concrete token
+        :param int position: The position of the token in the stream.
         """
         if _token_followed_by_eol(self._tokens, position):
             self._cont_stack.append(
diff --git a/pylint/checkers/logging.py b/pylint/checkers/logging.py
index cfbf74cf9..f6ee8dbe0 100644
--- a/pylint/checkers/logging.py
+++ b/pylint/checkers/logging.py
@@ -183,7 +183,8 @@ class LoggingChecker(checkers.BaseChecker):
         """Checks that function call is not format_string.format().
 
         Args:
-          callfunc_node: CallFunc AST node to be checked.
+          callfunc_node (astroid.node_classes.NodeNG):
+            CallFunc AST node to be checked.
         """
         if is_method_call(callfunc_node, ('str', 'unicode'), ('format',)):
             self.add_message('logging-format-interpolation', node=callfunc_node)
@@ -192,8 +193,8 @@ class LoggingChecker(checkers.BaseChecker):
         """Checks that format string tokens match the supplied arguments.
 
         Args:
-          node: AST node to be checked.
-          format_arg: Index of the format string in the node arguments.
+          node (astroid.node_classes.NodeNG): AST node to be checked.
+          format_arg (int): Index of the format string in the node arguments.
         """
         num_args = _count_supplied_tokens(node.args[format_arg + 1:])
         if not num_args:
@@ -235,10 +236,10 @@ def _count_supplied_tokens(args):
     arguments that aren't keywords.
 
     Args:
-      args: List of AST nodes that are arguments for a log format string.
+      args (list): AST nodes that are arguments for a log format string.
 
     Returns:
-      Number of AST nodes that aren't keywords.
+      int: Number of AST nodes that aren't keywords.
     """
     return sum(1 for arg in args if not isinstance(arg, astroid.Keyword))
 
diff --git a/pylint/checkers/utils.py b/pylint/checkers/utils.py
index 84e127c70..ae4f69127 100644
--- a/pylint/checkers/utils.py
+++ b/pylint/checkers/utils.py
@@ -404,6 +404,7 @@ def get_argument_from_call(callfunc_node, position=None, keyword=None):
     :param str keyword: the keyword of the argument.
 
     :returns: The node representing the argument, None if the argument is not found.
+    :rtype: astroid.Name
     :raises ValueError: if both position and keyword are None.
     :raises NoSuchArgumentError: if no argument at the provided position or with
     the provided keyword.
diff --git a/pylint/extensions/_check_docs_utils.py b/pylint/extensions/_check_docs_utils.py
index 70054e9ab..fe6cb1808 100644
--- a/pylint/extensions/_check_docs_utils.py
+++ b/pylint/extensions/_check_docs_utils.py
@@ -51,6 +51,7 @@ def possible_exc_types(node):
 
 
     :param node: The raise node to find exception types for.
+    :type node: astroid.node_classes.NodeNG
 
     :returns: A list of exception types possibly raised by :param:`node`.
     :rtype: list(str)
@@ -129,7 +130,7 @@ class SphinxDocstring(Docstring):
         (\w+)                   # Parameter name
         \s*                     # whitespace
         :                       # final colon
-        """.format(type=re_type, xref=re_xref), re.X | re.S)
+        """.format(type=re_type), re.X | re.S)
 
     re_type_in_docstring = re.compile(r"""
         :type                   # Sphinx keyword
@@ -137,7 +138,7 @@ class SphinxDocstring(Docstring):
         ({type})                # Parameter name
         \s*                     # whitespace
         :                       # final colon
-        """.format(type=re_type, xref=re_xref), re.X | re.S)
+        """.format(type=re_type), re.X | re.S)
 
     re_raise_in_docstring = re.compile(r"""
         :raises                 # Sphinx keyword
@@ -151,7 +152,7 @@ class SphinxDocstring(Docstring):
         (\w+)                   # Parameter name
         \s*                     # whitespace
         :                       # final colon
-        """.format(type=re_type, xref=re_xref), re.X | re.S)
+        """.format(type=re_type), re.X | re.S)
 
     re_rtype_in_docstring = re.compile(r":rtype:")
 
diff --git a/pylint/extensions/docparams.py b/pylint/extensions/docparams.py
index 26d4fb5f6..2f9d79a8e 100644
--- a/pylint/extensions/docparams.py
+++ b/pylint/extensions/docparams.py
@@ -276,6 +276,7 @@ class DocstringParameterChecker(BaseChecker):
         :type missing_excs: list
 
         :param node: The node show the message on.
+        :type node: astroid.node_classes.NodeNG
         """
         if not missing_excs:
             return
diff --git a/pylint/graph.py b/pylint/graph.py
index a46a345c8..05dd104a4 100644
--- a/pylint/graph.py
+++ b/pylint/graph.py
@@ -57,8 +57,9 @@ class DotBackend(object):
     def generate(self, outputfile=None, dotfile=None, mapfile=None):
         """Generates a graph file.
 
-        :param outputfile: filename and path [defaults to graphname.png]
-        :param dotfile: filename and path [defaults to graphname.dot]
+        :param str outputfile: filename and path [defaults to graphname.png]
+        :param str dotfile: filename and path [defaults to graphname.dot]
+        :param str mapfile: filename and path
 
         :rtype: str
         :return: a path to the generated file
diff --git a/pylint/pyreverse/diadefslib.py b/pylint/pyreverse/diadefslib.py
index 9e6b5b240..43549270b 100644
--- a/pylint/pyreverse/diadefslib.py
+++ b/pylint/pyreverse/diadefslib.py
@@ -201,9 +201,15 @@ class DiadefsHandler(object):
         self.config = config
 
     def get_diadefs(self, project, linker):
-        """get the diagrams configuration data
-        :param linker: pyreverse.inspector.Linker(IdGeneratorMixIn, LocalsVisitor)
-        :param project: pyreverse.utils.Project
+        """Get the diagrams configuration data
+
+        :param project:The pyreverse project
+        :type project: pyreverse.utils.Project
+        :param linker: The linker
+        :type linker: pyreverse.inspector.Linker(IdGeneratorMixIn, LocalsVisitor)
+
+        :returns: The list of diagram definitions
+        :rtype: list(:class:`pylint.pyreverse.diagrams.ClassDiagram`)
         """
 
         #  read and interpret diagram definitions (Diadefs)
diff --git a/pylint/utils.py b/pylint/utils.py
index 527c22284..655677337 100644
--- a/pylint/utils.py
+++ b/pylint/utils.py
@@ -794,13 +794,13 @@ class ReportsHandlerMixIn(object):
 def _basename_in_blacklist_re(base_name, black_list_re):
     """Determines if the basename is matched in a regex blacklist
 
-    :param base_name: The basename of the file
-    :param black_list_re: A collection of regex patterns to match against. Successful matches are
-                          blacklisted.
-    :returns: `True` if the basename is blacklisted, `False` otherwise.
+    :param str base_name: The basename of the file
+    :param list black_list_re: A collection of regex patterns to match against.
+        Successful matches are blacklisted.
 
+    :returns: `True` if the basename is blacklisted, `False` otherwise.
+    :rtype: bool
     """
-
     for file_pattern in black_list_re:
         if file_pattern.match(base_name):
             return True