Python docstring

The documentation is essential for any programming to understand the code easily. It is used to explain the purpose of using any statement or function or class or module in the program. It helps the main coder remember the function of any code after a long time, and It also helps other coders who want to work on the same project. The coder uses a single line of comment to explain the particular part of the code's function shortly. Python document string or docstring is used to explain the function of a particular segment of the code in detail. The docstring line should begin with the capital letter and end with a period. The first line of the docstring contains a short description of the documentation generally. The second line of the docstring should be blank for the large multi-line docstring. Triple single quotes('”) or triple double quotes(“””) are used to define the docstring in Python. The docstring content can be accessed by using the __doc__ attribute of the object and using the help() method. The way of declaring and accessing docstring in Python have shown in this tutorial.

Example-1: Accessing docstring of a function using __doc__ attribute

The way of declaring and accessing the docstring of a custom function has shown in the following script. The following script calculates the xⁿ where x and n will be taken from the user. Power () function has defined in the script to do the task. Here, the docstring has been defined for this function. __doc__ attribute has been used in the script to print the docstring with the output.

def power(x, n):
"Calculate x to the power n
Read the values of x and n from the function arguments
and Calculate and return the value of x to the power n."
return x**n
# Take the value of x
x = int(input('Enter the value of x:'))
# Take the value of n
n = int(input('Enter the value of n:'))
# Print the return value of the funnction
print("The %d to the power %d = %d" %(x, n, power(x, n)))
# Print the docstring value
print("The content of the docstring:\n" + power.__doc__)

Output:

The following output will be appeared after executing the above script.

Example-2: Accessing docstring of class and method using help() method

The way of declaring and accessing the document's docstring and the methods of that class has shown in the following script. The script's main function is to sort a numeric list and reverse the data of the list. A numeric list of 8 elements has been declared in the class, and the docstring has been defined at the beginning of the class by using triple single quotes. The sort_list() method has been defined in the class to print the sorted data of the list, and the document has defined this for this method. reverse_list() method is defined to print the list's reversed data, and the docstring has also been defined for this method. help() method has called three times at the end of the script to print the docstring of the list_operations class, sort_list() method, and the reverse_list() method.

class list_operations:

class list_operations:
"
Sorting and reversing the list data
The class contains two methods,
sort_list() method will sort and print the list,
sort_reverse() method will reverse and print the list.
"
# Define a list of numeric data
listdata = [23, 67, 23, 6, 45, 3, 90, 11]
def sort_list(self):
"
Print the list values after sorting
The function will take a list object of numeric data from the argument,
sort the list values using the sort() method
and print the values of the sorted list.
"
# Sort the list
self.listdata.sort()
# Print the sorted list using loop
print("The values of the sorted list:\n")
for value in self.listdata:
print(value, " ", end=")
def reverse_list(self):
"
Print the list values after reversing
The function will take a list object of numeric data from the argument,
reverse the list values using the reverse() method
and print the values of the reversed list.
"
# Reverse the list
self.listdata.reverse()
# Print the reversed list using loop
print("The values of the sorted list:\n")
for value in self.listdata:
print(value, " ", end=")
# Print the docstring value of the class
help(list_operations)
# Create object of the class
obj = list_operations()
# Print the docstring value of the particular method
help(obj.sort_list)
# Call the method to print the sorted list
obj.sort_list()

Output:

The following output will appear after executing the script. All docstring of the script has been printed for the first help() function. The docstring of the sort_list() method has been printed for the second help() function.

Example-3: Accessing docstring of the built-in Python module

In the previous examples, the docstring has used in user-defined class and function. Every built-in Python module and class has its docstring that explains the purpose of using that particular module or function. The coder of the module or function defines the docstring to make the code understandable for the users. The following script will print the pre-defined docstring of the datetime module by using the help() function.

# Import datetime module
import datetime
# Display the docstring of datetime
help(datetime)

Output:

The following output will be appeared after executing the script. The docstring of the datetime module shows the detailed documentation of it to help the others to know the functions of the classes and methods defined in this module properly.

Conclusion:

The proper documentation is essential when any module or function is implemented for the specific purpose to help the other coder to use the module in their code to do the particular task. If the documentation is not properly defined for the module or function, the other users will face problems using it. So, every coder has to use the document's docstring to provide detailed information for the others to understand the code.