Python Docstrings



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?

  • The document line must start with a capital letter and end with a period.
  • The first line should contain a short description.
  • If there are more lines in the docstring, the second line should be blank, visually separating the summary from the rest of the description.
  • The following lines should be one or more paragraphs describing the calling conventions of the object, its side effects, etc.

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.

def my_function ():

& quot; & quot; "Demonstrates docstrings and doesn`t actually do anything." & quot; & quot;

 

return None

 

print "Using __doc__:"

print my_function .__ doc__

 

print "Using help:"

help (my_function)

Output:

 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. 
For example:

def power (a, b):

& quot; & quot; "Returns arg1 raised to the power of arg2." & quot; & quot;

 

return a * * b

 

print power .__ doc__

Output:

 Returns arg1 raised to power arg2. 

Multi-Line Documents

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.

def my_function (arg1):

"" "

Summary line.

 

Extended function description.

 

  Parameters:

arg1 (int): arg1 description

 

Returns:

int: Description of the return value

 

"" "

  

return arg1

 

print my_function .__ doc__

Output:

 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.

class ComplexNumber:

"" "

  This is a class for mathematical operations on complex numbers.

  

Attributes:

real (int): real part of a complex number.

imag (int): imaginary part of a complex number.

  " ""

 

  def __ init __ ( self , real, imag):

"" "

Constructor for the ComplexNumber class.

 

Parameters:

real (int): real part of a complex number.

imag (int): imaginary part of a complex number.

  "" "

  

  def add ( self , num):

"" "

  Function for adding two complex numbers.

 

Parameters:

num (ComplexNumber): the complex number to be added.

 

Returns:

ComplexNumber: a complex number that contains the amount.

  " ""

 

re = self . real + num.real

im = self . imag + num.imag

 

return ComplexNumber (re, im)

  

help (ComplexNumber)  # for access to the documentation class

help (ComplexNumber.add)  # access the method document line

Exit:

 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.