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

Path	csiph.com!usenet.pasdenom.info!goblin2!goblin.stu.neva.ru!newsfeed.xs4all.nl!newsfeed1.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path	<alec.taylor6@gmail.com>
X-Original-To	python-list@python.org
Delivered-To	python-list@mail.python.org
X-Spam-Status	OK 0.001
X-Spam-Evidence	'H': 1.00; 'S': 0.00; '"""': 0.05; 'data):': 0.07; 'data:': 0.07; 'defines': 0.07; '"""get': 0.09; 'dict': 0.09; 'rfc': 0.09; 'def': 0.10; 'arbitrarily': 0.16; 'docstring': 0.16; 'it..': 0.16; 'subject: \n ': 0.16; 'subject:? - ': 0.16; 'subject:non': 0.16; 'syntax,': 0.16; 'trying': 0.21; 'libraries': 0.22; 'seems': 0.23; 'extend': 0.26; 'message-id:@mail.gmail.com': 0.27; 'post': 0.28; 'extending': 0.29; 'to:addr:python-list': 0.33; 'received:google.com': 0.34; 'subject:?': 0.35; 'but': 0.36; 'data.': 0.36; 'skip:g 30': 0.36; 'data': 0.37; 'some': 0.38; 'to:addr:python.org': 0.39; 'your': 0.60; 'containing': 0.61; 'more': 0.63; 'charset:windows-1252': 0.65
DKIM-Signature	v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:x-received:date:message-id:subject:from:to :content-type:content-transfer-encoding; bh=oTMi0KuEfhmHQpkMGc4lv3P7HbnZ8xvieYETlBMdNuE=; b=sQmiy1jKJD4yMr4W10KERRvaY8/Aw9YKIEhtteTfNSdX+fxfd0YH886rpw4T1DrWQj 4aBY7NBr3XHYzDagSt5Ygb8voMp5WkRjGejOKpcR+RIxXIt6MZHIGRPUUfpTBF721WOI ZM2iONHyVRt+/7y+2mEVTUxYvs5fe//n4ITSWpHXG1ABhSOzD/wtaVCV4NnG8b7wR/IZ FGnzTFDl8OLZdCBM1TszWaRoGm2PvXbVyHsn/0uX0rucNoAcZ8A4WJCJ99+eYCns/YM8 Lw8G7iF3+17YL8jj7xVTDoy1FohJ1Y4esojTHqWMqq5q3EHL9eEJF0CZMTJGDorvLdmD g6tQ==
MIME-Version	1.0
X-Received	by 10.50.33.139 with SMTP id r11mr832250igi.63.1361643294809; Sat, 23 Feb 2013 10:14:54 -0800 (PST)
Date	Sun, 24 Feb 2013 05:14:54 +1100
Subject	Should Docstrings include RFC citations? - And are non PEP257 syntaxes frowned upon?
From	Alec Taylor <alec.taylor6@gmail.com>
To	"comp.lang.python" <python-list@python.org>
Content-Type	text/plain; charset=windows-1252
Content-Transfer-Encoding	quoted-printable
X-BeenThere	python-list@python.org
X-Mailman-Version	2.1.15
Precedence	list
List-Id	General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe	<http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive	<http://mail.python.org/pipermail/python-list/>
List-Post	<mailto:python-list@python.org>
List-Help	<mailto:python-list-request@python.org?subject=help>
List-Subscribe	<http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups	comp.lang.python
Message-ID	<mailman.2363.1361643304.2939.python-list@python.org> (permalink)
Lines	24
NNTP-Posting-Host	2001:888:2000:d::a6
X-Trace	1361643304 news.xs4all.nl 6988 [2001:888:2000:d::a6]:37137
X-Complaints-To	abuse@xs4all.nl
Xref	csiph.com comp.lang.python:39692

Show key headers only | 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