What is docstring in Python?

Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods. As you can see, even for a relatively simple function, documenting using comments quickly makes it unpleasant and difficult to read. So, to solve this, the docstring was introduced. A docstring is simply a multi-line string, that is not assigned to anything. It is specified in source code that is used to document a specific segment of code. Unlike conventional source code comments, the docstring should describe what the function does, not how. All modules should normally have docstrings , and all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings. A package may be documented in the module docstring of the __init__.py file in the package directory.

One-line Docstrings

One-liners are for really obvious cases. They should really fit on one line . Depending on the complexity of the function, method, or class being written, a one-line docstring may be perfectly appropriate. These are generally used for really obvious cases, such as:

def sum(x, y): """Returns arg1 value add to arg2 value.""" return a+b print sum.__doc__

Output:

Returns arg1 value add to arg2 value.

In larger or more complex projects however, it is often a good idea to give more information about a function, what it does, any exceptions it may raise, what it returns, or relevant details about the parameters . For more detailed documentation of code a popular style is the one used for the Numpy project , often called Numpy style docstrings. example

def generic_socket(param1, param2): """ Summary generic_socket. Extended description of generic_socket. Parameters ---------- param1 : int Description of param1 (port) param2 : str Description of param2 (ipaddress) Returns ------- int Description of return value """ return 42

The sphinx.ext.napoleon plugin allows Sphinx to parse this style of docstrings, making it easy to incorporate NumPy style docstrings into your project. The docstring should describe the function in a way that is easy to understand. Tools like Sphinx will parse your docstrings as reStructuredText and render it correctly as HTML. This makes it very easy to embed snippets of example code in a project’s documentation. Most Python documentation is written with reStructuredText . It's like Markdown with all the optional extensions built in. However, docstrings seem to be far more personal than other areas of code. Different projects will have their own standard.

Next : What is the difference between runtime and compile time?

Related Topics