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-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:
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.
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.