This is great, and something I am also writing. Are you able to share the full
code? It would be best to demonstrate it as an extension either way.
On Thu, Jul 24, 2014 at 10:55 AM, Daniel, Bruno
<bruno.dan...@blue-yonder.com> wrote:
> Dear pylint developers,
> We use pylint extensively in our company -- thanks this great tool! -- and
> wrote some plugins ourselves to aid us in our daily work. One of these plugins
> is a Sphinx parameter documentation checker that helps us to identify missing
> parameter or parameter type documentation in functions, methods and class
> constructors (__init__ methods).
> The checker class also identifies naming inconsistencies between each function
> or method signature and the corresponding docstring.
> By convention, we use Sphinx syntax for the parameter documentation (see below
> for examples) and we document class constructor parameters in the class
> docstring.
> We want to offer this code to you as a optional standard pylint checker. Would
> such an addition to pylint be welcome?
> To illustrate, here are our unit tests which include several examples:
> -snip----- test_pylint_plugin.py
> ----------------------------------------------
> """Unittest for our pylint plugin."""
> from __future__ import division, print_function
> import unittest
> from astroid import test_utils
> from pylint.testutils import CheckerTestCase, Message, set_config
> from nbpy_devel.pylint_plugin import SphinxDocChecker, NbpyChecker
> class SpinxDocCheckerTest(CheckerTestCase):
> """Tests for pylint_plugin.SphinxDocChecker"""
> CHECKER_CLASS = SphinxDocChecker
> def test_missing_func_params_in_docstring(self):
> """Example of a function with missing parameter documentation in the
> docstring
> """
> node = test_utils.extract_node("""
> def function_foo(x, y):
> '''docstring ...
> missing parameter documentation'''
> pass
> """)
> with self.assertAddsMessages(
> Message(
> msg_id='W9003',
> node=node,
> args=('x, y',)),
> Message(
> msg_id='W9004',
> node=node,
> args=('x, y',))):
> self.checker.visit_function(node)
> def test_missing_method_params_in_docstring(self):
> """Example of a class method with missing parameter documentation in
> the
> docstring
> """
> node = test_utils.extract_node("""
> class Foo(object):
> def method_foo(self, x, y):
> '''docstring ...
> missing parameter documentation'''
> pass
> """)
> method_node = node.body[0]
> with self.assertAddsMessages(
> Message(
> msg_id='W9003',
> node=method_node,
> args=('x, y',)),
> Message(
> msg_id='W9004',
> node=method_node,
> args=('x, y',))):
> self.checker.visit(node)
> def test_existing_func_params_in_docstring(self):
> """Example of a function with correctly documented parameters and
> return
> values
> """
> node = test_utils.extract_node("""
> def function_foo(xarg, yarg):
> '''function foo ...
> :param xarg: bla xarg
> :type xarg: int
> :param yarg: bla yarg
> :type yarg: float
> :return: sum
> :rtype: float
> '''
> return xarg + yarg
> """)
> with self.assertNoMessages():
> self.checker.visit_function(node)
> def test_wrong_name_of_func_params_in_docstring(self):
> """Example of functions with inconsistent parameter names in the
> signature and in the documentation
> """
> node = test_utils.extract_node("""
> def function_foo(xarg, yarg):
> '''function foo ...
> :param xarg1: bla xarg
> :type xarg: int
> :param yarg: bla yarg
> :type yarg1: float
> '''
> return xarg + yarg
> """)
> with self.assertAddsMessages(
> Message(
> msg_id='W9003',
> node=node,
> args=('xarg, xarg1',)),
> Message(
> msg_id='W9004',
> node=node,
> args=('yarg, yarg1',))):
> self.checker.visit_function(node)
> node = test_utils.extract_node("""
> def function_foo(xarg, yarg):
> '''function foo ...
> :param yarg1: bla yarg
> :type yarg1: float
> For the other parameters, see bla.
> '''
> return xarg + yarg
> """)
> with self.assertAddsMessages(
> Message(
> msg_id='W9003',
> node=node,
> args=('yarg1',)),
> Message(
> msg_id='W9004',
> node=node,
> args=('yarg1',))):
> self.checker.visit_function(node)
> def test_see_sentence_for_func_params_in_docstring(self):
> """Example for the usage of "For the other parameters, see" to avoid
> too many repetitions, e.g. in functions or methods adhering to a given
> interface
> """
> node = test_utils.extract_node("""
> def function_foo(xarg, yarg):
> '''function foo ...
> :param yarg: bla yarg
> :type yarg: float
> For the other parameters, see :func:`bla`
> '''
> return xarg + yarg
> """)
> with self.assertNoMessages():
> self.checker.visit_function(node)
> def test_constr_params_in_class(self):
> """Example of a class with missing constructor parameter documentation
> Everything is completely analogous to functions.
> """
> node = test_utils.extract_node("""
> class ClassFoo(object):
> '''docstring foo
> missing constructor parameter documentation'''
> def __init__(self, x, y):
> pass
> """)
> with self.assertAddsMessages(
> Message(
> msg_id='W9003',
> node=node,
> args=('x, y',)),
> Message(
> msg_id='W9004',
> node=node,
> args=('x, y',))):
> self.checker.visit_class(node)
> if __name__ == '__main__':
> unittest.main()
> -----------------------------------------------------------------------------
> Kind regards
> Bruno Daniel
> ----
> Dr. Bruno Daniel
> Research and Development
> bruno.dan...@blue-yonder.com
> www.blue-yonder.com
> _______________________________________________
> code-quality mailing list
> code-quality@python.org
> https://mail.python.org/mailman/listinfo/code-quality_______________________________________________
code-quality mailing list
code-quality@python.org
https://mail.python.org/mailman/listinfo/code-quality
