Do some doc string validateion
Project description
validatedoc
Validates my extremely specific opinions of what python function docstrings should look like.
I recommend using this with pydocstyle, which velidates pep257. This is more strict and more opinionated than that.
Installing
pip install validatedoc
Usage
validatedoc file1.py dir/file2.py file2.py
More info
Example of how it expects docs to be formated:
def foo(bar, baz, qux) -> zam:
"""Do foo thing to bar baz and qux and produce zam.
:param bar: a thing
:param baz: another thing
:param qux: more
:raises FooError: when foo goes wrong
:raises ValueError: if a value is wrong
:return: the value of Zam
"""
...
Specifically, it ensures that:
- There is an empty newline between the description and parameters list
- Parameters are in the format
:param name: description
- Exception docstrings are in the format
:raises exception: description
- Return docstrings look like
:return: description
, and come after all raises and param doc strings - There are no empty newlines in the param/raises/return list
- Lines in the param/raises/return list either start an item or have a four space indent (to continue the previous line)
- The params match exactly the arguments
- Return docstrings are last
- If the function is annotated to return None, no return should be present
- If the function specifies a return other than none, return is present
In the future, I also want to:
- Verify that any exceptions raised in the function have a raises docstring
- Better support *args and **kwargs (right now they're considered normal args that require a single param each if they're in the function definition)
- Validate docstrings on things other than functions
- Validate the short and long descriptions in some way
- Something with types
- Require param/raises/return lines to start with a lowercase or an uppercase (and decide which to use)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
validatedoc-0.0.3.tar.gz
(4.7 kB
view hashes)
Built Distribution
Close
Hashes for validatedoc-0.0.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e278e60bdc20a13788103e900c84759d0ddb86f0fe921af5659465df7403e828 |
|
MD5 | 332d3421d1f451fc842ef55b1ba7675f |
|
BLAKE2b-256 | 06ff873d4ba5cebda9727707d02925e82f77782ae8e377df7fbb7ccdf5d2dae4 |