How to find undocumented methods in my code?

Question

I am writing documentation for a project and I would like to make sure that I have not missed a single method. The code is written in Python and I use PyCharm as an IDE.

Basically, I need REGEX to match something like:

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

but it must NOT match:

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

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

Answer 1

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

And your regex has problems. First of all, as noted in the comments, you may have to avoid the closing parenthesis. Secondly, you do not match the new line following the function declaration. Finally, you are looking for single or double quotes in the START string, but the beginning of the string contains spaces.

I managed to match your file with a sample \):\s*\n\s*["'] . This is a multi-line regular expression. Not all programs can match a multi-line regular expression. For example, with grep you will need to use this method .

A brief explanation of what matches this regex: it looks for a closing bracket, followed by a semicolon. Any number of optional spaces may follow. Then there should be a new line, followed by any number of spaces (in this case, indentation). Finally, there must be a single or double quotation mark. Note that this corresponds to functions that have comments. You want to invert this to find those who have.

Answer 2

You mentioned that you are using PyCharm: there is a "Missing, empty or incorrect docstring" check that you can enable and will do for you.

Please note that you can change the severity so that it appears more or less noticeably.

Answer 3

If PyCharm is not available, there is a small tool called ckdoc written in Python 3.5 .

Given one or more files, it finds modules, classes, and functions without docstring. It does not search the imported built-in or external libraries - it considers objects defined in files located in the same folder as the given file or subfolders of this folder.

Usage example (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 times when this does not work. One such case is using Anaconda with modules . A possible workaround in this case is to use ckdoc from the Python shell. Import the 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.

Answer 4

There is a tool called pydocstyle that checks if all classes, functions, etc. are formatted correctly. docstrings.

Example from 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 do not know about PyCharm, but pydocstyle can, for example, be integrated into Vim using the Syntastic plugin .