Python Rules Of Coding: Docstrings

previous
Python Rules Of Coding: String literals

Source

Python Rules Of Coding: Docstrings

Python docstring (documentation string) is a string literal and it can be used in any code block, i.e., the class, module, function, method definition. It provides us a handy way of attaching the relevant documentation within the code block. It describes the source code.

We generally use comments for documentation of a single line code, statement, and expressions which are usually small and not so explanatory.

Remember, this does not diminish the importance of comments use.

Docstrings are a descriptive text and better for easily understanding the functionality, the purpose of the code block.

When a programmer creates class, module, function, he/she associates the documentation for another developer to know what the purpose or what does of that class, module, function.

So that other developer who wishes to contribute to that project can easily grasp the understanding of this code block without having to read the details of the implementation.

We can use Python documentation generators like Sphinx to generate HTML documentation automatically from Docstrings.

The source code documentation (Docstrings) can be accessed using the built-in __doc__attribute or using the help function.

As PEP 257 -- Docstring Conventions, we should use
" " " triple double quotes " " " in docstrings.
r " " " raw triple double quotes " " " escape backslashes in docstrings.
u" " " Unicode triple quoted strings" " " for unicode docstrings.

We are familiar with two forms of docstrings.

1. One-line Docstrings
2. Multi-line Docstrings

One-line Docstrings :

class Sensor:
     def __init__(self, calc=0.0):
    “ “ “Initialize the Sensor object with the given warmth value.” “ “
    
     self.set_temperature(Calc)
     return

Notes from PEP 257 -- Docstring Conventions :

1. Use triple double-quotes.
2. Keep the closing quotes in the same line as with the opening quotes.
3. No need a blank line either before or after the docstring.

def square(b):
       “ “ “ Returned argument b is squared.” “ “
      return b**b
      print(square.__doc__)    #using __doc__ attribute

Output

Returned argument b is squared.

We can also access to the docstring using the built-in help function

def square(b):
     “ “ “ Returned argument b is squared.” “ “
    return b**b
   help(square)         # using help function

Output

Help on function square in module __main__:

square(b)
    Returned argument a is squared.

Multi-line Docstring:

The form of multi-line docstrings is the same as a one-line docstring, but it is a more elaborate description.

def  my_func(dev1): 
   """ 
   Summary line. 

   Elaborated description of function. 

   Parameters: 
   dev1(int): Description of dev1 

   Returns: 
   int: Description of return value 

   """

   return  dev1

   print my_func.__doc

Output

Summary line. 

   Elaborated description of function. 

   Parameters: 
   dev1(int): Description of dev1 

   Returns: 
   int: Description of return value

______________________

Next

Operator Precedence