Skip to content

Instantly share code, notes, and snippets.

@danielmacuare
Last active March 8, 2020 11:19
Show Gist options
  • Save danielmacuare/2b09ba36efb7199eadf2090c91c1e454 to your computer and use it in GitHub Desktop.
Save danielmacuare/2b09ba36efb7199eadf2090c91c1e454 to your computer and use it in GitHub Desktop.
Python Docstrings Formats

Python Docstrings

Type of Docstrings


Examples

  • Google Dosctrings
    • Documenting a Function
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

  • Documenting a Class
class ExampleError(Exception):
    """Exceptions are documented in the same way as classes.

    The __init__ method may be documented in either the class level
    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one
    convention to document the __init__ method and be consistent with it.

    Note:
        Do not include the `self` parameter in the ``Args`` section.

    Args:
        msg (str): Human readable string describing the exception.
        code (:obj:`int`, optional): Error code.

    Attributes:
        msg (str): Human readable string describing the exception.
        code (int): Exception error code.

    """

    def __init__(self, msg, code):
        self.msg = msg
        self.code = code

  • Restructured Text (reST)
    • Documenting a Function
def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    :param temp: the temperature value
    :type temp: float
    :return: no value
    :rtype: none
    """

    self.temperature = float(temp)
    return
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment