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.
Related Topics
- Python Interview Questions (Part 2)
- Python Interview Questions (Part 3)
- What is python used for?
- Is Python interpreted, or compiled, or both?
- Explain how python is interpreted
- How do I install pip on Windows?
- How do you protect Python source code?
- What are the disadvantages of the Python?
- How would you achieve web scraping in Python?
- How to Python Script executable on Unix
- What is the difference between .py and .pyc files?
- What is __init__.py used for in Python?
- What does __name__=='__main__' in Python mean?
- What is the difference between runtime and compile time?
- How to use *args and **kwargs in Python
- Purpose of "/" and "//" operator in python?
- What is the purpose pass statement in python?
- Why isn't there a switch or case statement in Python?
- How does the ternary operator work in Python?
- What is the purpose of "self" in Python
- How do you debug a program in Python?
- What are literals in python?
- What is Python's parameter passing mechanism?
- What is the process of compilation and Loading in python?
- Global and Local Variables in Python
- Is there a tool to help find bugs or perform static analysis?
- What does the 'yield' keyword do in Python?
- Comparison Operators != is not equal to in Python
- What is the difference between 'is' and '==' in python
- What is the difference between = and == in Python?
- How are the functions help() and dir() different?
- What is the python keyword "with" used for?
- Is all the memory freed when Python exits?
- Difference between Mutable and Immutable in Python
- Explain split() methods of "re" module in Python
- Accessor and Mutator methods in Python
- How to Implement an 'enum' in Python
- Important characteristics of Python Objects
- How to determine the type of instance and inheritance in Python
- How would you implement inheritance in Python?
- How is Inheritance and Overriding methods are related?
- How can you create a copy of an object in Python?
- How to avoid having class data shared among instances in Python?
- Static class variables in Python
- Difference between @staticmethod and @classmethod in Python
- How to Get a List of Class Attributes in Python
- Does Python supports interfaces like in Java or C#?
- What is used to create Unicode string in Python?
- Difference between lists and tuples in Python?
- What are differences between List and Dictionary in Python
- Different file processing modes supported by Python
- How do you append to a file in Python?
- What are the differences between the threading and multiprocessing?
- Is there any way to kill a Thread in Python?
- What is the use of lambda in Python?
- What is map, filter and reduce in python?
- Is monkey patching considered good programming practice?
- What is "typeerror: 'module' object is not callable"
- Python: TypeError: unhashable type: 'list'
- How to convert bytes to string in Python?
- What are metaclasses in Python?