Documenting Python, part 2 |
<Part 1< |
More info from the Python Style Guide:
The doc string for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's doc string.)
The doc string for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.
The doc string for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the doc string). The class constructor should be documented in the doc string for its __init__ method. Individual methods should be documented by their own doc string.
If a class subclasses another class and its behavior is mostly inherited from that class, its doc string should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).
Python is case sensitive and the argument names can be used for keyword arguments, so the doc string should document the correct argument names. It is best to list each argument on a separate line, with two dashes separating the name from the description
If you've made it this far, I'll help you out and summarize what you just learned. Python has a documentation feature called doc string that allows you to use comments to create self-documenting source code. Several Python IDE's, such as SPE, can use these doc strings to create a listing of your source code structures, such as classe and modules. This makes it easier on the programmer since less work is required when you create your help files and other program documentation. Documentation indexers can pull the doc strings out of your code and make a listing for you, or you could even make your own script to create it for you.
However, the only way to harness the power of doc strings is to follow the style rules Python expects, meaning you have to use triple-quotes, separate your summary line from the full-blown description, etc. You can document your Python code without following these rules but then it's up to you to create a help file or whatever.
Not only will it make your life easier when you finish your project, but it also makes your code easier to read and follow. (Wish the people at my work could learn how to document their code. Even just a few comments explaining what a function does would help. :-) )