Commit bb6012d
authored
Propose docstring style for repo (#272)
Here is a proposal for how to structure docstrings in
protovalidate-python going forward (at least when porting the rest of
the validation implementations). I think this strikes the right balance
of adhering to best practices while not being onerous.
* Functions being added to the library should get the bulk of the
comment description in a docstring. No need to define `Args:`,
`Raises:`, etc. though.
* Any other public function, class, etc. should preferably have
docstrings, though not necessary.
* Be as succinct as possible while also keeping comments across
implementations consistently worded.
For validation following an RFC / spec:
* Always include any relevant ABNF grammar and keep aligned.
* Indent grammar inside docstring.
One suggestion outside the scope of this PR might be to always have full
docstring (`Args`, `Raises`, etc.) on any public method the user
interacts with (i.e. stuff in `validator.py`)1 parent 12fa3e5 commit bb6012d
1 file changed
Lines changed: 82 additions & 127 deletions
0 commit comments