While the comments are utilized for programs, statements, and expressions, which are typically brief, docstrings are excellent for understanding the functioning of the larger portion of the script like the general use of any module, class, or function. They are a description of a line of code or statement produced by a programmer that is usually for themselves to understand what it does. It is crucial to document your code properly if you want to write programs with clear code and good documentation. The docstrings are supplied, employing the “triple single quotes” or “triple double quotes” right after the function, class, or method definition.
Example 1: Program of Python Docstring Triple Single Quotes
Either the object’s __doc__ method or the help function can be used to obtain the docstrings. The declaration and use of a docstring with the triple single quotes are shown in the following examples:
Begin with defining a function in Python. We creat a function as my_func(). Within the body of the my_func, we have as a docstring wrapped around the triple single quotes. Then, at the end of the function, we explicitly execute the return statement which returns the none value. The print function takes my_func with the _doc_ object that will display the docstring. Furthermore, we have a Python help function which is used to print the documentation of the my_func function.
When this particular program is debugged and run, it generates the following results in the console screen of Spyder:
Example 2: Program of Python Docstring Triple Double Quotes
The following code deploys the docstring declaration and use with the triple double-quotes:
Here, we give a function name my_func2. Inside the body of the my_func2, we declare a docstring with the triple-double quote. Then, we call the Python’s _doc_ object to print the specified docstring and the documentation of the function my_func2 with the help function.
The outcomes generated from the aforementioned codes are as follows. This output is generated by the execution of the previous affixed code in Spyder:
Example 3: Program of Python One-Line Docstring
One-line docstrings are just what their name suggests: one line. They’re employed in blatant situations. The last quotes are situated on a similar line as the initial ones. For one-liners, this appears more appealing.
Here, we construct a function as “add” which takes two arguments: x and y. Then, we declare the one-line docstring inside the body of the “add” function definition. The return statement returns the value from the addition of the two values. The print statement is invoked for displaying the docstring inside the add function by utilizing the _doc_ object.
The results of the one-line docstring are shown in the following Spyder console screen. This output is generated by the execution of the above affixed code in Spyder:
Example 4: Program of a Python Multi-Line Docstring
Similar to the one-line docstrings, the multi-line docstrings start with a summary line and end with a blank line before describing something in greater detail. The summary line can appear on a similar line as the beginning quotations or on a different line. A multiline docstring is demonstrated in the following instance:
In this particular example script, we have the function definition which is given a name as python_function. This function takes an argument value x. The function body is declared with the multi-line string which is the description of the argument value and the int data type. After that, the return command is defined. The multiline docstring is displayed by calling the _doc_ object inside the print function.
The multi-lines of the docstring are printed on the Spyder terminal as follows:
Example 5: Program of Python Docstring Indentation
The quotations at its initial line are indented the same amount as the rest of the docstring. Every indentation in the docstring’s first line (up with the first newline) is unnecessary and should be eliminated. Afterward, the lines in the docstring keep their relative indentation. As an illustration on how to create the docstrings for a class and its methods, let’s look at an example. The access to the docstring is through help:
We define a class with the keyword Class and name that class as my_python_example. Inside the class my_python_example, we declare the docstring which is surrounded by the triple double-quotes. Then, we create the function square which has the input x and the function is also declared with the docstring. Then, we create another function with the name, cube. It also takes an input n. This function is created for the cube of the number. This statement is explained by the docstring declaration. After that, we have a Python help function to execute the documentation of the my_python_program class and the function square.
From the previously mentioned Python program, the following output listed is obtained. This output is generated by the execution of the previously affixed code in Spyder:
Conclusion
The main goal of this course is to familiarize you with the docstrings by going through the foundational ideas. However, because docstrings is such a broad topic, it is possible that some ideas were skipped over. To get a function’s documentation, use the help() function. Put a string, either a single-line string or a multi-line string, in the function’s first line to add the documentation.
