NumPy docstring is the short form of a NumPy documentation string. NumPy docstrings provide a convenient way to associate the documentation with NumPy modules, functions, classes, and methods. In this guide, we will learn how to create the docstrings in NumPy and we will try to understand when, how, and where they are used. Docstrings are multi-line comments inside functions, methods, modules, classes, etc. Before learning the docstrings, let’s understand what the multiline comments are.

Since we already know how to write the multiline comments, we may either use the triple single quotes or triple double quotes. We use a documentation string when we want to describe our functions so that we can get the documentation when we need it. Some IDEs give you documentation by just hovering over the name and some highlight certain keywords. But the fact is that docstrings in NumPy are way more flexible than in other languages. Docstring is a string literal that occurs at the start of the function definition. We have to provide specific values while using the docstrings in cases of functions, classes, etc.

When using docstrings with functions, we have to pass the arguments. When using them with classes, we pass the attributes and methods. In the case of Modules, we have to provide a list of classes and functions. In the case of the package, we pass the list of modules with functionality. So basically, the purpose of the docstring is, as the name explains, that it helps with the documentation of our code. We do documentation so that if someone uses our code in the future, he will be able to understand our code and the logic behind our code with the help of docstring. Built-in functions also have docstrings in them; we can use the function of help() to look at the docstring of built-in functions.

There are a few differences between comments and docstrings. Comments are ignored by interpreters but docstrings are not ignored by interpreters. Memory is allocated for docstrings. A comment is a description of code but on the other hand, docstrings tell us the purpose of code.

Syntax:

The syntax to write the docstrings in NumPy is:

Please note that docstring is not a function or method, so it does not have proper syntax. The only thing to note here is that we start the docstring with three single quotes or three double quotes. We write our description of the code and end it again with three single quotes or three double quotes at the end. There is no mandatory thing to write for docstrings. You just have to put three single or double quotes before and after your string description.

Example 1:

To understand the docstrings in a better way, let’s perform an example. In this example, after including the NumPy library, we simply declare the variable “a” and another variable “b”. After that, we create our docstring which says “Let us add “a” and “b” variables”. In our case, this is an easy example but if our code is complex, this helps the coder a lot in understanding the code. After that, we sum up the variables “a” and “b” and store their output result in another variable which is “c”. Finally, we print the value of the variable “c”. Now, we execute our code.

This is our output from the given piece of code. We can see that the system has not given any error about incorrect syntax or anything for line7 of our code. Also, the system has not printed our docstring. Instead, it only printed the output of our variable “c” in which we told our system to print. This shows how the docstrings work. Next time, when a new coder tries to work on our code, he will understand what are we doing with the help of our docstring. But it will not be printed as output so the user of the code will not be disturbed by it.

Example 2:

Now, we perform a complex example to understand the docstring’s working. First, we include the NumPy library and then write a doc string in which we explain the next line of code where we explain the initialization of the array. We also add the docstrings in the other part of the code. Now, if we share this code with any new Python developer without adding the docstrings, it will somehow be difficult for him to know the working and the purpose of this code. He has to search first about the functions that we used. But if we add a docstring to our code, it will be easy for the other developers to understand the code without studying more about the functions. We are not restricted to adding comments to some limits; comments can be of one or more than one line. It can also be added more than once in a code. Then, import NumPy as np.

As shown in the following snippet, docstrings are not displayed in the output which means that it doesn’t affect the output or compilation of the code. Docstrings are ignored during the compilation process.

Conclusion

In this guide, we learned about docstrings in NumPy. We compared the docstrings with comments and explained the difference between both of them. We learned the syntax of docstrings and how to write the docstrings in our code. Furthermore, we also tried to explain what the docstrings in NumPy are and how they work with the help of examples. Finally, we remarked that they are essential for coders. We will not repeat the importance of docstrings in NumPy. We will just say that you should use the docstrings in your code. In NumPy, the writing style of docstrings is the most popular one. It is widely used in the programming community to let each other know about the working and functionality of their codes. This guide will help you get started with NumPy docstrings. We tried to cover most of what you will need using the docstrings in NumPy.