There are several docstring formats that are commonly used in Python. Some of the most popular formats include:
def divide(dividend, divisor): """Divide two numbers. Args: dividend (float): The number to be divided. divisor (float): The number to divide by. Returns: float: The quotient of the division. Raises: ZeroDivisionError: If the divisor is zero. Examples: >>> divide(10, 2) 5.0 """ if divisor == 0: raise ZeroDivisionError("Cannot divide by zero") return dividend / divisor |
def gaussian(x, mu, sigma): """Calculate the value of a Gaussian distribution at point x. Parameters ---------- x : float The point at which to evaluate the Gaussian distribution. mu : float The mean of the distribution. sigma : float The standard deviation of the distribution. Returns ------- float The value of the Gaussian distribution at point x. Raises ------ ValueError If sigma is not positive. Notes ----- The Gaussian distribution is given by: f(x) = (1 / (sigma * sqrt(2 * pi))) * exp(-((x - mu) ** 2) / (2 * sigma ** 2)) """ if sigma <= 0: raise ValueError("sigma must be positive") return (1 / (sigma * math.sqrt(2 * math.pi))) * math.exp(-((x - mu) ** 2) / (2 * sigma ** 2)) |
def fibonacci(n): """ Compute the nth Fibonacci number. :param n: The index of the Fibonacci number to compute. :type n: int :returns: The nth Fibonacci number. :raises ValueError: If n is negative. Examples: >>> fibonacci(0) 0 >>> fibonacci(1) 1 >>> fibonacci(10) 55 """ if n < 0: raise ValueError("n must be non-negative") if n == 0: return 0 if n == 1: return 1 return fibonacci(n-1) + fibonacci(n-2) |
Each format has its own conventions and advantages, and the choice of format depends on personal preference and the needs of the project. It's important to be consistent within a project, and to make sure that the docstrings are clear, informative, and easy to read.