Skip to content

Commit bb6012d

Browse files
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

File tree

0 commit comments

Comments
 (0)