Docstring Templates

See the Google python style guide for general guidelines.

2017/03/06 these are @bplimley's ideas, can be discussed and revised.

General guidelines

• First line is a concise summary statement that fits on one line. It can be on the same line as the opening triple-quote, or a new line
• After a blank line, additional description can be added. Basic examples are good to include here
• First line and multi-line descriptions use sentence case
• Below additional description, there are sections listing arguments/attributes (see below)
• If one of these sections is empty, the header need not be included either
• Section items indented 2 spaces beyond section header
• Each item in the sections should describe acceptable data types (as applicable)
• Each input or output value with units should explicitly mention the units
• If section items wrap lines, hanging indent is an extra 2 spaces
• Period at the end of the sentence is not necessary
• Section item descriptions need not start with a capital letter

Functions and methods

• Sections include "Args", "Returns", and "Raises"
• Defaults provided in [default: ] if relevant, or if an arg has fixed allowable values (like modes) then one of them could be marked [default]
• Can mark an argument as (optional) if needed
• Methods need never list self as an argument

def some_function(arg1, arg2=None, arg3=None, mode='asdf'):
    """Single-line description of what this function does. <80 characters.

    If I need more space to adequately describe what this function does, I can
    put it here on as many lines as needed.
    Example: x = some_function('asdf', arg2=np.arange(10))

    Args:
      arg1: a string representing blah blah blah
      arg2 (optional): an iterable of floats for energies in keV. Maybe I 
        need a longer description and it must wrap to a new line
      arg3: the peak width to blah blah blah [default: 3 keV]
      mode: defines how the Foo is constructed
        'asdf' [default]: this means blah blah blah
        'qwerty': another mode that does blah blah blah

    Returns:
      an instance of Foo from the energies in arg2 blah blah blah

    Raises:
      TypeError: if arg1 is not a string
      SpectrumError: for blah blah blah
    """

    foo = bar()   # code begins here

Classes

• Docstring contains an overview of what the class is, and concise descriptions of attributes. Specific details of attributes are given in the docstring for each attribute
• Sections include ("Abstract properties", "Abstract methods",) "Data attributes", "Properties", and "Methods"
• Only public attributes are described
• Mark a property as (read-only) if it has no setter
• __init__() doesn't need to be described in the top-level class docstring, but __init__() has its own docstring
• Classes inheriting public properties and methods should include such attributes in the class docstring.

class Qwerty(object):
    """
    Abstract base class for a blah blah blah.

    Longer multi-line description if necessary. Use Levenberg-Marquadt to do
    fitting magic blah blah blah.

    Abstract methods:
      fit: produce new calibration curve based on current calibration points

    Properties:
      foo (read-only): list of the channel values of blah blah blah
      bar (read-only): indicates the current status of blah blah blah

    Methods:
      add_peak: add a peak for blah blah
      rm_peak: remove a peak from blah blah
    """

    class_var = 3.14  # code or __init__ begins here