Python doc comment

How to write Python document comments (Docstrings). Hi, a faction? school? There seems to be.

Short Summary: A brief one-line description. Name

NumPy style.py


def add(a, b):
"""The sum of two numbers.

"""


Google style.py


def add(a, b):
"""The sum of two numbers.

"""


Extended Summary: A detailed summary of multiple lines

NumPy style.py


def add(a, b):
"""The sum of two numbers.

(Extended Summary)
"""


Google style.py


def add(a, b):
"""The sum of two numbers.

(Extended Summary)
"""


Parameters: Function arguments

NumPy style.py


"""
Parameters
----------
x : type
Description of parameter x.
y
Description of parameter y (with type not specified)
"""


Google style.py


"""
Args:
x (type): Description of parameter x.
y: Description of parameter y (with type not specified)
"""


Returns: Function returns

NumPy style.py


"""
Returns
-------
int
Description of anonymous integer return value.
"""


NumPy style.py


"""
Returns
-------
err_code : int
Non-zero value indicates error code, or zero on success.
err_msg : str or None
Human readable error message, or None on success.
"""


Google style.py


"""
Returns:
int: Description of anonymous integer return value.
"""


Raises: Exception

NumPy style.py


"""
Raises
------
LinAlgException
If the matrix is not numerically invertible.
"""


Google style.py


"""
Raises:
LinAlgException: If the matrix is not numerically invertible.
"""


See Also: Related items

NumPy style.py


"""
See Also
--------
average : Weighted average
"""


Google style.py


#None


Notes: Remarks. Additional description. You can also use LaTeX.

NumPy style.py


"""
Notes
----------
The FFT is a fast implementation of the discrete Fourier transform:
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
"""


Google style.py


"""
Note:
The FFT is a fast implementation of the discrete Fourier transform:
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
"""


Examples: Usage examples

NumPy style.py


"""
Examples
----------
>>> np.add(1, 2)
3
"""


Google style.py


"""
Example:
>>> np.add(1, 2)
3
"""


Attributes: Class attributes

NumPy style.py


"""
Attributes
----------
x : float
The X coordinate.
y : float
The Y coordinate.
"""


Google style.py


"""
Attributes:
x (float): The X coordinate.
y (float): The Y coordinate.
"""


Methods: methods of the class

NumPy style.py


"""
Methods
-------
colorspace(c='rgb')
Represent the photo in the given colorspace.
gamma(n=1.0)
Change the photo's gamma exposure.
"""


Google style.py


#None