previous
Python Rules Of Coding: String literals
Python Rules Of Coding: Docstrings
Python docstring (documentation string) is a string literal and it can be used in any code block, i.e., the class, module, function, method definition. It provides us a handy way of attaching the relevant documentation within the code block. It describes the source code.
We generally use comments for documentation of a single line code, statement, and expressions which are usually small and not so explanatory.
Remember, this does not diminish the importance of comments use.
Docstrings are a descriptive text and better for easily understanding the functionality, the purpose of the code block.
When a programmer creates class, module, function, he/she associates the documentation for another developer to know what the purpose or what does of that class, module, function.
So that other developer who wishes to contribute to that project can easily grasp the understanding of this code block without having to read the details of the implementation.
We can use Python documentation generators like Sphinx to generate HTML documentation automatically from Docstrings.
The source code documentation (Docstrings) can be accessed using the built-in __doc__attribute or using the help function.
As PEP 257 -- Docstring Conventions, we should use
" " " triple double quotes " " " in docstrings.
r " " " raw triple double quotes " " " escape backslashes in docstrings.
u" " " Unicode triple quoted strings" " " for unicode docstrings.
We are familiar with two forms of docstrings.
- One-line Docstrings
- Multi-line Docstrings
One-line Docstrings :
class Sensor:
def __init__(self, calc=0.0):
“ “ “Initialize the Sensor object with the given warmth value.” “ “
self.set_temperature(Calc)
return
Notes from PEP 257 -- Docstring Conventions :
- Use triple double-quotes.
- Keep the closing quotes in the same line as with the opening quotes.
- No need a blank line either before or after the docstring.
def square(b):
“ “ “ Returned argument b is squared.” “ “
return b**b
print(square.__doc__) #using __doc__ attribute
Output
Returned argument b is squared.
We can also access to the docstring using the built-in help function
def square(b):
“ “ “ Returned argument b is squared.” “ “
return b**b
help(square) # using help function
Output
Help on function square in module __main__:
square(b)
Returned argument a is squared.
Multi-line Docstring:
The form of multi-line docstrings is the same as a one-line docstring, but it is a more elaborate description.
def my_func(dev1):
"""
Summary line.
Elaborated description of function.
Parameters:
dev1(int): Description of dev1
Returns:
int: Description of return value
"""
return dev1
print my_func.__doc
Output
Summary line.
Elaborated description of function.
Parameters:
dev1(int): Description of dev1
Returns:
int: Description of return value
______________________