Check for docstring existence and format #113

Closed
JensRantil opened this Issue Jul 26, 2012 · 5 comments

Projects

None yet

3 participants

@JensRantil
Contributor

From PEP8:

Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the def line.

Since private modules, functions and classes all are not prepended I suggest checking only non-prepended modules, functions and classes.

Further, PEP8 states:

PEP 257 describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, and preferably preceded by a blank line, e.g.:

(this should trigger a warning)

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.

"""

For one liner docstrings, it's okay to keep the closing """ on the same line.

Member
myint commented Jul 27, 2012

The pep257 utility checks for this.

Contributor

The pep257 utility checks for this.

Great! Since PEP8 referes to PEP257, how about

  1. Proposing to pep257 to publish a PyPi package and create/pull request an API.
  2. Creating a dependency in pep8's setup.py and incorporate the tests that pep257 comes with into pep8's testsuite.

?

Member
myint commented Jul 27, 2012

Dependencies seem undesirable to me. There are already tools that combine functionality. For example, flake8 combines pep8 with two other tools. I would guess it wouldn't be difficult to add pep257's code into it.

Contributor

Dependencies seem undesirable to me. There are already tools that combine functionality. For example, flake8 combines pep8 with two other tools. I would guess it wouldn't be difficult to add pep257's code into it.

Aight. Would you be happier if docstring checks were incorporated into pep8 instead? No dependencies, duplicate code instead.

Since PEP257 is part of PEP8, I would expect pep8 to include checks for it. Otherwise if should be stated in readme it does not make those checks and never will. I was expecting it to contain checks for it, simply based on the name of this Python package... :-/

Contributor

I've updated the documentation with clarification about such feature.

@florentx florentx closed this Dec 22, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment