Proposal to extend PEP 257 (New Documentation String Spec)

[rantingrick]

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.