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 <rantingr...@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 > -- http://mail.python.org/mailman/listinfo/python-list
