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

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=85

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?