This is my proposal:
Quick example:
def foo(self):
"""
Returns foo.
"""
pass
Mutiple paragraphs & word wrapping example:
def foo(self):
"""
Python isn't perfect, but it's
the coolest language in the
world.
And Webware is the coolest
Python product. :-)
"""
pass
Formatting Rules:
- Use """ only.
- Put string delimiters on their own line.
- Put a blank line in between paragraphs.
- Hard wrapping.
- Don't exceed col 79, assuming tab=8.
- For a method doc string using tab=4, that would be 71.
Language guidelines:
- First word should be an action verb:
Returns....
Processes...
Sends...
- First sentence should sum up the method quickly. The rest of the docs
should give details.
Dispatches the given request to the correct servlet and returns the
resulting transacton. Blah blah blah...
- If the purpose of the method is strongly tied to another method's
implementation consider adding the statement:
Invoked by foo().
And in foo():
Invokes bar().
Not all cross calls need to be documented, but some are very important.
- If the method is abstract include the statement:
Subclass responsibility.
and don't forget to:
from MiscUtils import SubclassResponsbilityError
raise SubclassResponsbilityError, self.__class__
- If the method is rarely overridden because there is another, better
hook for customizing the behavior, don't be afraid to say so:
Subclasses usually override _draw() instead of draw() which contains
both pre- and post- drawing code.
I successfully tested the formatting with pydoc, kate and emacs. Hope
you like it!
-Chuck
_______________________________________________
Webware-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/webware-devel
