pylint documentation: Demonstrate parameter documentation checking for Google and Numpy style as well.

1 files changed, 76 insertions, 10 deletions

diff --git a/doc/extensions.rst b/doc/extensions.rst
index 1e80097..204fde3 100644
--- a/doc/extensions.rst
+++ b/doc/extensions.rst
@@ -2,18 +2,24 @@
 Optional Pylint checkers in the extensions module
 =================================================
 
-Sphinx parameter documentation checker
---------------------------------------
+Parameter documentation checker
+-------------------------------
 
-If you're using Sphinx to document your code, this optional component might
-be useful for you. You can activate it by adding the line::
+If you document the parameters of your functions, methods and constructors and
+their types systematically in your code this optional component might
+be useful for you. Sphinx style, Google style, and Numpy style are supported.
+(For some examples, see https://pypi.python.org/pypi/sphinxcontrib-napoleon .)
+
+You can activate this checker by adding the line::
 
     load-plugins=pylint.extensions.check_docs
 
 to the ``MASTER`` section of your ``.pylintrc``.
 
 This checker verifies that all function, method, and constructor parameters are
-mentioned in the Sphinx ``param`` and ``type`` parts of the docstring::
+mentioned in the
+
+* Sphinx ``param`` and ``type`` parts of the docstring::
 
    def function_foo(x, y, z):
        '''function foo ...
@@ -31,16 +37,55 @@ mentioned in the Sphinx ``param`` and ``type`` parts of the docstring::
        '''
        return x + y + z
 
+* or the Google style ``Args:`` part of the docstring::
+
+   def function_foo(x, y, z):
+       '''function foo ...
+
+       Args:
+           x (int): bla x
+           y (float): bla y
+
+           z (int): bla z
+
+       Returns:
+           float: sum
+       '''
+       return x + y + z
+
+* or the Numpy style ``Parameters`` part of the docstring::
+
+   def function_foo(x, y, z):
+       '''function foo ...
+
+       Parameters
+       ----------
+       x: int
+           bla x
+       y: float
+           bla y
+
+       z: int
+           bla z
+
+       Returns
+       -------
+       float
+           sum
+       '''
+       return x + y + z
+
+
 You'll be notified of **missing parameter documentation** but also of
 **naming inconsistencies** between the signature and the documentation which
-often arise when parameters are renamed automatically in the code, but not in the
-documentation.
+often arise when parameters are renamed automatically in the code, but not in
+the documentation.
 
 By convention, constructor parameters are documented in the class docstring.
 (``__init__`` and ``__new__`` methods are considered constructors.)::
 
     class ClassFoo(object):
-        '''docstring foo
+        '''Sphinx style docstring foo
 
         :param float x: bla x
 
@@ -50,6 +95,16 @@ By convention, constructor parameters are documented in the class docstring.
         def __init__(self, x, y):
             pass
 
+    class ClassFoo(object):
+        '''Google style docstring foo
+
+        Args:
+            x (float): bla x
+            y (int): bla y
+        '''
+        def __init__(self, x, y):
+            pass
+
 In some cases, having to document all parameters is a nuisance, for instance if
 many of your functions or methods just follow a **common interface**. To remove
 this burden, the checker accepts missing parameter documentation if one of the
@@ -62,7 +117,7 @@ following phrases is found in the docstring:
 docstring defining the interface, e.g. a superclass method, after "see"::
 
    def callback(x, y, z):
-       '''callback ...
+       '''Sphinx style docstring for callback ...
 
        :param x: bla x
        :type x: int
@@ -72,5 +127,16 @@ docstring defining the interface, e.g. a superclass method, after "see"::
        '''
        return x + y + z
 
-Naming inconsistencies in existing ``param`` and ``type`` documentations are
+   def callback(x, y, z):
+       '''Google style docstring for callback ...
+
+       Args:
+           x (int): bla x
+
+       For the other parameters, see
+       :class:`MyFrameworkUsingAndDefiningCallback`
+       '''
+       return x + y + z
+
+Naming inconsistencies in existing parameter and their type documentations are
 still detected.