Should Docstrings include RFC citations? - And are non PEP257 syntaxes frowned upon?

Alec Taylor alec.taylor6 at
Sat Feb 23 19:14:54 CET 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