Proposal to extend PEP 257 (New Documentation String Spec)

[Michael Hrivnak]

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
>