How to find undocumented methods in my code?

Question

I am writing documentation for a project and I would like to make sure I did not miss any method. The code is written in Python and I am using PyCharm as an IDE.

Basically, I would need a REGEX to match something like:

def method_name(with, parameters):
    someVar = something()
    ...

but it should NOT match:

def method_name(with, parameters):
    """ The doc string """
    ...

I tried using PyCharm's search with REGEX feature with the pattern ):\s*[^"'] so it would match any line after : that doesn't start with " or ' after whitespace, but it doesn't work. Any idea why?

`)` is a special character, use `\)`. Example: http://regexr.com?35aei — David Starkey, Jun 21 '13 at 15:58
Can't you do something more reliable by accessing `__doc__`? — YXD, Jun 21 '13 at 15:59
There are modules in the standard library to process python language (tokenizer, syntax trees...). Why using a regex? — michaelmeyer, Jun 21 '13 at 16:00
Note that you can **assign** documentation afterwards. `method_name.__doc__ = 'Documentation for method_name'. — Martijn Pieters, Jun 21 '13 at 16:00
Instead of using a regex, I would suggest running your code through Pylint, it can detect when a docstring is missing. — Andrew Clark, Jun 21 '13 at 16:02
You can't use regexps, because Python is not a [regular language](http://en.wikipedia.org/wiki/Regular_language). — msw, Jun 21 '13 at 16:18
@F.J pylint would be a solution, but I didn't want to install it just for this project. Thank you — Ciprian Tomoiagă, Jun 25 '13 at 07:41

Thomas Orozco · Answer 1 · 2013-06-21T16:21:35.750

6

You mentioned you were using PyCharm: there is an inspection "Missing, empty, or incorrect docstring" that you can enable and will do that for you.

Note that you can then change the severity for it to show up more or less prominently.

enter image description here

edited Jun 21 '13 at 16:21

answered Jun 21 '13 at 16:08

Thomas Orozco

53,284
11
113
116

1

this is useful, thank you. but it is a bit too general. I was able to make it report missing documentation by using *Code > Run Inspection by Name* , but it also reported for classes, modules, missing parameters etc, which is too much for what I wanted – Ciprian Tomoiagă Jun 25 '13 at 07:40

score 3 · Answer 2 · answered Jun 30 '17 at 07:40

There is a tool called pydocstyle which checks if all classes, functions, etc. have properly formatted docstrings.

Example from the README:

$ pydocstyle test.py
test.py:18 in private nested class `meta`:
        D101: Docstring missing
test.py:27 in public function `get_user`:
    D300: Use """triple double quotes""" (found '''-quotes)
test:75 in public function `init_database`:
    D201: No blank lines allowed before function docstring (found 1)

I don't know about PyCharm, but pydocstyle can, for example, be integrated in Vim using the Syntastic plugin.

score 2 · Accepted Answer · edited May 23 '17 at 11:33

I don't know python, but I do know my regex.

And your regex has issues. First of all, as comments have mentioned, you may have to escape the closing parenthesis. Secondly, you don't match the new line following the function declaration. Finally, you look for single or double quotations at the START of a line, yet the start of a line contains whitespace.

I was able to match your sample file with \):\s*\n\s*["']. This is a multiline regex. Not all programs are able to match multiline regex. With grep, for example, you'd have to use this method.

A quick explanation of what this regex matches: it looks for a closing parenthesis followed by a semicolon. Any number of optional whitespace may follow that. Then there should be a new line followed by any number of whitespace (indentation, in this case). Finally, there must be a single or double quote. Note that this matches functions that do have comments. You'd want to invert this to find those without.

thank you. for getting only the methods I added a def in front, like this: `def [a-z_\(\) ,=*]*\):\s*\n\s*[a-z\n]` this does the job. — Ciprian Tomoiagă, Jun 25 '13 at 07:37

score 0 · Answer 4 · edited Jun 20 '20 at 09:12

In case PyCharm is not available, there is a little tool called ckdoc written in Python 3.5.

Given one or more files, it finds modules, classes and functions without a docstring. It doesn't search in imported built-in or external libraries – it only considers objects defined in files residing in the same folder as the given file, or subfolders of that folder.

Example usage (after removing some docstrings)

> ckdoc/ckdoc.py "ckdoc/ckdoc.py"
ckdoc/ckdoc.py
    module
        ckdoc
    function
        Check.documentable
        anykey_defaultdict.__getitem__
        group_by
        namegetter
    type
        Check

There are cases when it doesn't work. One such case is when using Anaconda with modules. A possible workaround in that case is to use ckdoc from Python shell. Import necessary modules and then call the check function.

> import ckdoc, main
> ckdoc.check(main)
/tmp/main.py
    module
        main
    function
        main
/tmp/custom_exception.py
    type
        CustomException
    function
        CustomException.__str__
False

The check function returns True if there are no missing docstrings.

How to find undocumented methods in my code?

4 Answers4