What is Docstring?
Python docstrings (or docstrings) provide a convenient way to link documentation to Python modules, functions, classes, and methods.
This is stated in the source code. which is used as a comment to document a specific segment of code. Unlike regular source comments, the docstring should describe what the function does, not how.
What should the docstring look like?
Declaration docstrings: doc strings are declared using “” “triple double quotes” “” just below a class, method, or function declaration. All functions must have a docstring.
Document Rows Access: Document rows can be accessed using the __doc__ object method or using the help function.
The example below shows how to declare and access the docstring.
Using __doc__: Demonstrate docstrings and does nothing really. Using help: Help on function my_function in module __main__: my_function () Demonstrate docstrings and does nothing really.
Single Line Documents
As the name suggests, one line of documentation fits on one line. They are used in obvious cases. The closing quotation marks are on the same line as the opening quotation marks. It looks better for one-liners.
Returns arg1 raised to power arg2.
Multi-line docstrings consist of a summary line, similar to a single document line, followed by a blank line with more detailed descriptions. The summary string can be on the same line as the opening quotation marks, or on the next line.
The example below shows a multi-line docstring.
Summary line. Extended description of function. Parameters: arg1 (int): Description of arg1 Returns: int: Description of return value
Indent in Docstrings
The entire line of the document has one the same indentation as the quotes on the first line. The docstring tools will separate the same amount of indentation from the second and subsequent lines of a document line, equal to the minimum indentation of all nonblank lines after the first line. Any indentation on the first line of a line in the document (i.e. before the first newline) is negligible and removed. The relative indentation of later lines in the document line is preserved.
Document lines in classes
Let`s take an example to show how to write docstrings for class and its methods. help is used to access the docstring.
Help on cla ss ComplexNumber in module __main__: class ComplexNumber | This is a class for mathematical operations on complex numbers. | | Attributes: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | Methods defined here: | | __init __ (self, real, imag) | The constructor for ComplexNumber class. | | Parameters: | real (int): The real part of complex number. | imag (int): The imaginary part of complex number. | | add (self, num) | The function to add two Complex Numbers. | | Parameters: | num (ComplexNumber): The complex number to be added. | | Returns: | ComplexNumber: A complex number which contains the sum. Help on method add in module __main__: add (self, num) unbound __main __. ComplexNumber method The function to add two Complex Numbers. Parameters: num (ComplexNumber): The complex number to be added. Returns: ComplexNumber: A complex number which contains the sum.
This article is courtesy of Mayank Agrawal . If you are as Python.Engineering and would like to contribute, you can also write an article using contribute.python.engineering or by posting the article [email protected] … See my article appearing on the Python.Engineering homepage and help other geeks.
Please post comments if you find anything wrong or if you`d like to share more information on the topic discussed above.