Take a look at the plugin manager for an example of what good method doc comments look like:
    https://github.com/Freeseer/freeseer/blob/master/src/freeseer/framework/plugin.py

Typically I try to use the format.

Line 1, short summary of what method does.
Line 2, Blank line
Line 3, Long description of what the method does (use as many lines as necessary).
Last few lines Parameter and Return list.