Define and Demonstrate Docstring Usage in Candelatech Python Scripts

Any docstrings occurring after the attribute docstring will be referred to as “additional docstrings“. Docstrings in Python are defined as a string literal that is the first statement in a module, function, class or method definition. Such string literals are referred to as “attribute docstrings” and will become the __doc__ attribute of the module, function, class, or method in which they are used.

PEP 257 establishes a standard for docstring usage. In order to keep consistency, triple double quotes should be used for all docstrings. Single-line docstrings should be contained entirely on one line. In the example given, a docstring for a function should briefly describe its purpose and specify the return type.

Example taken from PEP 257 page:

def function(a, b):
  """Do X and return a list."""
      

Multi-line docstrings should consist of a brief one line summary, followed by a blank line, and finally followed by a more elaborate description. The summary line may either be inline with the opening quotes or on the next line and the whole docstring should be on the same line of indentation as the opening and closing quotations. Closing quotes should exist on their own line, if part of a multi-line docstring, to prevent confusion.

Example taken from PEP 257 page:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
      return complex_zero
    ...
      

Implementing Docstring Conventions With Candelatech Script Template

Candelatech scripts will follow PEP 257 specifications for module, function, class or method definitions. To keep things standardized the following example will cover the preferred format for module level docstrings.

#!/usr/bin/env python3
"""Module overview/one line description

More detailed summary of module, elaborate on when to use module/
test coverage of full script (Pass/ Fail conditions, columns/ information tested)

External scenario requirements:

Cookbook: http://www.candelatech.com/cookbook.php?vol=cli&book=_______

Copyright 2021 Candela Technologies Inc
License: Free to distribute and modify. LANforge systems must be licensed.
"""