Docstrings in Python
Learn about the different types of docstrings and various docstring formats like Sphinx, Numpy and Pydoc.
If you are just getting started in Python and would like to learn more, take DataCamp's Introduction to Data Science in Python course.
Python documentation string or commonly known as docstring, is a string literal, and it is used in the class, module, function, or method definition. Docstrings are accessible from the doc attribute (__doc__) for any of the Python objects and also with the built-in help() function. An object's docstring is defined by including a string constant as the first statement in the object's definition.
Docstrings are great for understanding the functionality of the larger part of the code, i.e., the general purpose of any class, module, or function, whereas the comments are used for code, statement, and expressions, which tend to be small. They are a descriptive text written by a programmer mainly for themselves to know what the line of code or expression does and also for the developer who wishes to contribute to that project. It is an essential part that documenting your code is going to serve well enough for writing clean code and well-written programs.
Docstrings help you understand the capabilities of a module or a function. For example, let's say you installed the scikit-learn library and you would like to know all about the sklearn package like description, package modules, etc., you could simply use the help function to get all the information.
Let's quickly import the package.
import sklearn#help(sklearn)Docstrings vs. Commenting
Docstrings are similar in spirit to commenting, but they are enhanced, more logical, and useful version of commenting. Docstrings act as documentation for the class, module, and packages.
On the other hand, Comments are mainly used to explain non-obvious portions of the code and can be useful for comments on Fixing bugs and tasks that are needed to be done.
Docstrings are represented with closing & opening quotes while comments start with a # at the beginning.
Note that comments can not be accessed with the built-in doc attribute and help function. Let's see what happens if you try doing so:
def string_reverse(str1):
#Returns the reversed String.
#Parameters:
# str1 (str):The string which is to be reversed.
#Returns:
# reverse(str1):The string which gets reversed.
reverse_str1 = ''
i = len(str1)
while i > 0:
reverse_str1 += str1[i - 1]
i = i- 1
return reverse_str1
print(string_reverse.__doc__)help(string_reverse)There are a couple of ways of writing or using a Docstring, i.e., one-line docstring and multi-line docstring.
Let's learn them one by one.
One-Line Docstring
The one-line Docstrings are the Docstrings, which fits all in one line. You can use one of the quotes, i.e., triple single or triple-double quotes, and opening quotes and closing quotes need to be the same. In the one-line Docstrings, closing quotes are in the same line as with the opening quotes. Also, the standard convention is to use the triple-double quotes.
def square(a):
'''Returned argument a is squared.'''
return a**aprint (square.__doc__)help(square)From the above Docstring output, you can observe that:
- In this case, the line begins with a capital letter, i.e., R and ends with a period
(.). - The closing quotes are on the same line as the opening quotes. This looks better for one-liners.
- A good practice to follow is having no blank line either before or after the Docstring, as shown in the above example.
- The output of the
__doc__attribute is less verbose as compared to thehelp()function.
Multi-Line Docstring
Multi-line Docstrings also contains the same string literals line as in One-line Docstrings, but it is followed by a single blank along with the descriptive text.
The general format for writing a Multi-line Docstring is as follows:
def some_function(argument1):
"""Summary or Description of the Function
Parameters:
argument1 (int): Description of arg1
Returns:
int:Returning value
"""
return argument1
print(some_function.__doc__)