Should Docstrings include RFC citations? - And are non PEP257 syntaxes frowned upon?
Alec Taylor
alec.taylor6 at gmail.com
Sat Feb 23 13:14:54 EST 2013
PEP257 defines docstring syntax, but I find myself arbitrarily extending it.
I have seen some Flask libraries floating around which utilise this syntax:
def get_token_from_post_data(self, data):
"""Get a token response from POST data.
:param data: POST data containing authorization information.
:type data: dict
:rtype: requests.Response
"""
I am trying to conform to the PEP257 syntax, but find myself
arbitrarily extending it with RFC citations…
However this "Flask syntax" seems to be more readable!
So I was thinking to extend it like so:
:param <var>: <desc>
:param_ref <var>: <RFC section>
What's your take on these syntaxes?
More information about the Python-list
mailing list