Proposal to extend PEP 257 (New Documentation String Spec)
Michael Hrivnak
mhrivnak at hrivnak.org
Fri Jul 15 02:00:29 EDT 2011
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 markup?
Michael
On Thu, Jul 14, 2011 at 7:02 PM, rantingrick <rantingrick at 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.
>
> ---------------------------------------
> New Syntax Specification For Documentation Strings
> ---------------------------------------
>
> """ {DOC TAG HERE}: {MODULE_NAME|SHORT_SUMMARY_HERE}.
> {NEWLINE}
> {LONG_DESCRIPTION_HERE}
> {NEWLINE}
> Arguments: (if applicable)
> {ARGUMNET_1} <{TYPE}>:
> ARGUMENT_1_DESCRIPTION}
> {ARGUMNET_2} <{TYPE}>:
> ARGUMENT_2 DESCRIPTION}
> {ARGUMNET_N} <{TYPE}>:
> ARGUMENT_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.
>
> ---------------------------------------
> Example: Module Documentation String.
> ---------------------------------------
>
> """Module <simpledialog.py>:
>
> This module handles Tkinter dialog boxes.
> It contains the following public symbols:
>
> Dialog <class>:
> A base class for dialogs.
>
> askinteger <function>:
> Get an integer from the user.
>
> askfloat <function>:
> Get a float from the user.
>
> askstring <function>:
> Get 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.
>
> ---------------------------------------
> Example: Func/Meth Documentation String.
> ---------------------------------------
>
> def askinteger(parent, title, prompt, **kw):
> """ Interface: Get an integer from the user.
>
> Return value is an integer.
>
> Arguments:
> title <string>:
> the dialog title
> prompt <string|integer|float>:
> the label text
> **kw:
> see SimpleDialog class
>
>
> ---------------------------------------
> Example: Class Inheritance Documentation Strings.
> ---------------------------------------
>
> class Base():
> def __init__(self):
> """ Internal:"""
> self.m1()
>
> def m1(self, *args):
> """Overide: """
> pass
>
> class Derived(Base):
> def __init__(self):
> Base.__init__(self)
>
> def _m1(self):
> """ Internal: blah"""
>
> def m1(self):
> """ Clobbered: see Base for detail"""
>
> def m3(self):
> """ Interface: Blah"""
>
> ---------------------------------------
> Tags For Documentation Strings
> ---------------------------------------
>
> Module:
> The module tag is to be used for module doc strings.
>
> Virtual:
> The virtual tag is for methods residing in a base class
> that are created specifically to be overridden. Of course as we
> all know every Python methods/function is virtual by default
> however the point of this is to make the code more readable!
>
> Override:
> This tag should be placed in a derived class's method which has
> clobbered a base method. Typically you can just defer the reader
> to look up the base class for more info.
>
> Internal:
> This tag should be used on all internal methods (psst: the ones
> that
> start with a single underscore *ahem* or SHOULD start with a
> single
> underscore!).
>
> Interface:
> This tag is be used for interface method/function doc strings.
> This
> is probably the most important tag. If you don't do any tagging AT
> LEAST tag the interface methods and functions. However i must
> remind you that all these tags are very important.
>
> --
> http://mail.python.org/mailman/listinfo/python-list
>
More information about the Python-list
mailing list