Looks good. I like the 'first word is verb' bit and like how you
capitalize the synopsis.
Two things I'd change:
1) require the first LINE (not parag.) to be a synopsis of the method.
2) suggest, rather than require, that the """ be on a line by itself.
Emacs will automatically suck out the newline when I use
auto-wrapping.
So it would be:
def foo(self):
"""
Returns foo
More detailed info ...
"""
pass
or
def foo(self):
"""Returns foo
More detailed info ..."""
pass
NOT
def foo(self):
""<Start of first sentence> ...
... <rest of sent>
More detailed info ..."""
pass
or
def foo(self):
"""Returns foo.
More detailed info ..."""
pass
On Sunday 09 December 2001 13:24, Chuck Esterbrook wrote:
> 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
_______________________________________________
Webware-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/webware-devel
