Path: csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!weretis.net!feeder4.news.weretis.net!border2.nntp.ams2.giganews.com!border4.nntp.ams.giganews.com!border2.nntp.ams.giganews.com!nntp.giganews.com!feeder1.cambriumusenet.nl!feed.tweaknews.nl!194.134.4.91.MISMATCH!news2.euro.net!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
MIME-Version: 1.0
Sender: mhrivnak@gmail.com
In-Reply-To: <120629e8-3b37-4e8c-a472-cd361de15de4@g9g2000yqb.googlegroups.com>
References: <120629e8-3b37-4e8c-a472-cd361de15de4@g9g2000yqb.googlegroups.com>
Date: Fri, 15 Jul 2011 02:00:29 -0400
Subject: Re: Proposal to extend PEP 257 (New Documentation String Spec)
From: Michael Hrivnak <mhrivnak@hrivnak.org>
To: rantingrick <rantingrick@gmail.com>
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Cc: python-list@python.org
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.1043.1310709630.1164.python-list@python.org>
Lines: 166
NNTP-Posting-Host: 2001:888:2000:d::a6
Xref: x330-a1.tempe.blueboxinc.net comp.lang.python:9506

Was tried at least once before:
http://www.python.org/dev/peps/pep-0287/

Check in here with your ideas:
http://www.python.org/community/sigs/current/doc-sig/

Have any other languages mandated the use of a specific documentation marku=
p?

Michael

On Thu, Jul 14, 2011 at 7:02 PM, rantingrick <rantingrick@gmail.com> wrote:
>
> Hello Folks,
>
> Lately i have been musing over the ideas of method tagging.
> Specifically i am referring to method identifiers. As most of you know
> i had proposed to add "syntactical markers" to the language to deal
> with the ambiguities that arise whist eyeball parsing sub classed
> methods that clobber virtual methods. HOWEVER that idea caused some
> fierce controversy within the community, and i can partly understand
> why.
>
> Although i strongly believe in proper documentation (even to the point
> of forcing syntax on folks) i understand that we cannot implement such
> a thing without major growing pains. So with that being said, i have
> formulated a new battle plan to defeat this problem of ambiguity.
>
> Unlike most languages out there we have doc-strings; and do we realize
> how great this gift is? Sometimes i wonder because you folks should
> really be using them like they are going out of style!
>
> As we all know PEP 257 lays out some ground rules for documentation
> strings HOWEVER i feel this PEP did no go far enough. Too many folks
> are refusing to document properly and so i will take this time to
> hammer out a spec. I would like to comments for or against.
>
> ---------------------------------------
> =A0New Syntax Specification For Documentation Strings
> ---------------------------------------
>
> """ {DOC TAG HERE}: {MODULE_NAME|SHORT_SUMMARY_HERE}.
> {NEWLINE}
> {LONG_DESCRIPTION_HERE}
> {NEWLINE}
> Arguments: (if applicable)
> =A0 =A0{ARGUMNET_1} <{TYPE}>:
> =A0 =A0 =A0 =A0ARGUMENT_1_DESCRIPTION}
> =A0 =A0{ARGUMNET_2} <{TYPE}>:
> =A0 =A0 =A0 =A0ARGUMENT_2 DESCRIPTION}
> =A0 =A0{ARGUMNET_N} <{TYPE}>:
> =A0 =A0 =A0 =A0ARGUMENT_N_DESCRIPTION}
> {NEWLINE}
> """
>
> As you can see my spec introduces some new ideas to writing doc-
> strings. Specifically the "DOC TAG" and {ARG TYPES} are new. Also i've
> found it much more useful to separate args and their respective
> descriptions with a newline and indention.
>
> ---------------------------------------
> =A0Example: Module Documentation String.
> ---------------------------------------
>
> """Module <simpledialog.py>:
>
> This module handles Tkinter dialog boxes.
> It contains the following public symbols:
>
> =A0 =A0Dialog <class>:
> =A0 =A0 =A0 =A0A base class for dialogs.
>
> =A0 =A0askinteger <function>:
> =A0 =A0 =A0 =A0Get an integer from the user.
>
> =A0 =A0askfloat <function>:
> =A0 =A0 =A0 =A0Get a float from the user.
>
> =A0 =A0askstring <function>:
> =A0 =A0 =A0 =A0Get a string from the user.
>
> """
>
> I don't know how i feel about marking classes and functions since IF
> we follow the python style guide we don;t need to; but that's IF we
> FOLLOW it people, IF.
>
> ---------------------------------------
> =A0Example: Func/Meth Documentation String.
> ---------------------------------------
>
> def askinteger(parent, title, prompt, **kw):
> =A0 =A0""" Interface: Get an integer from the user.
>
> =A0 =A0Return value is an integer.
>
> =A0 =A0Arguments:
> =A0 =A0 =A0 =A0title <string>:
> =A0 =A0 =A0 =A0 =A0 =A0the dialog title
> =A0 =A0 =A0 =A0prompt <string|integer|float>:
> =A0 =A0 =A0 =A0 =A0 =A0the label text
> =A0 =A0 =A0 =A0**kw:
> =A0 =A0 =A0 =A0 =A0 =A0see SimpleDialog class
>
>
> ---------------------------------------
> =A0Example: Class Inheritance Documentation Strings.
> ---------------------------------------
>
> class Base():
> =A0 =A0def __init__(self):
> =A0 =A0 =A0 =A0""" Internal:"""
> =A0 =A0 =A0 =A0self.m1()
>
> =A0 =A0def m1(self, *args):
> =A0 =A0 =A0 =A0"""Overide: """
> =A0 =A0 =A0 =A0pass
>
> class Derived(Base):
> =A0 =A0def __init__(self):
> =A0 =A0 =A0 =A0Base.__init__(self)
>
> =A0 =A0def _m1(self):
> =A0 =A0 =A0 =A0""" Internal: blah"""
>
> =A0 =A0def m1(self):
> =A0 =A0 =A0 =A0""" Clobbered: see Base for detail"""
>
> =A0 =A0def m3(self):
> =A0 =A0 =A0 =A0""" Interface: Blah"""
>
> ---------------------------------------
> =A0Tags For Documentation Strings
> ---------------------------------------
>
> =A0Module:
> =A0 =A0The module tag is to be used for module doc strings.
>
> =A0Virtual:
> =A0 =A0The virtual tag is for methods residing in a base class
> =A0 =A0that are created specifically to be overridden. Of course as we
> =A0 =A0all know every Python methods/function is virtual by default
> =A0 =A0however the point of this is to make the code more readable!
>
> =A0Override:
> =A0 =A0This tag should be placed in a derived class's method which has
> =A0 =A0clobbered a base method. Typically you can just defer the reader
> =A0 =A0to look up the base class for more info.
>
> =A0Internal:
> =A0 =A0This tag should be used on all internal methods (psst: the ones
> that
> =A0 =A0start with a single underscore *ahem* or SHOULD start with a
> single
> =A0 =A0underscore!).
>
> =A0Interface:
> =A0 =A0This tag is be used for interface method/function doc strings.
> This
> =A0 =A0is probably the most important tag. If you don't do any tagging AT
> =A0 =A0LEAST tag the interface methods and functions. However i must
> =A0 =A0remind you that all these tags are very important.
>
> --
> http://mail.python.org/mailman/listinfo/python-list
>