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

Date	2013-02-24 05:14 +1100
Subject	Should Docstrings include RFC citations? - And are non PEP257 syntaxes frowned upon?
From	Alec Taylor <alec.taylor6@gmail.com>
Newsgroups	comp.lang.python
Message-ID	<mailman.2363.1361643304.2939.python-list@python.org> (permalink)

Show all headers | View raw

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?

Back to comp.lang.python | Previous | Next | Find similar | Unroll thread

Thread

Should Docstrings include RFC citations? - And are non PEP257 syntaxes frowned upon? Alec Taylor <alec.taylor6@gmail.com> - 2013-02-24 05:14 +1100

csiph-web