From: Chuck E. <Chu...@ya...> - 2001-12-09 21:24:50
|
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 |