Sphinx Docblock

[hallister]

In order to document our code properly, we are using a standard docblock for all methods/functions.

Here's an example:

   def function(name, state)
        """A short description.

        A long description that can use multiple lines. You don't need this, it's only useful if your 
        short description doesn't fully describe your function/method/objects purpose.

        :param name: The name to use.
        :type name: str.
        :param state: Current state to be in.
        :type state: bool.
        :returns:  int -- the return code.
        :raises: AttributeError, KeyError
        """
        return 3

Make sure you are only using the parameters your particular function (or class) uses. For example, if I don't have any parameters to my function, I won't need the :param or :type keys. If my function never returns (class method) don't add a :returns.

:raises should ONLY be used if your function can, at some point, raise that particular error/exception.

[cawaltrip]

Closing due to being moved to wiki: Documentation (Sphinx)