Skip to main content

Add Docstring to a Python Function

Docstring provide a convenient way of associating documentation with Python modules, functions, classes, and methods. It’s specified in source code that is used, like a comment, to document a specific segment of code. It also describe what the function does,not how.

Declaring Docstrings: The docstrings are declared using ”’triple single quotes”’ or “””triple double quotes””” just below the class, method or function declaration. All functions should have a docstring.

Accessing Docstrings: The docstrings can be accessed using the __doc__ method of the object or using the help function.

Rules for writing a docstrings:

  • There's no blank line either before or after the docstring.
  • If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description.
  • The doc string line should begin with a capital letter and end with a period.
  • Even though If there are single-lined, we still use the triple quotes around these docstrings as they can be expanded easily later.

Using triple double quotes

def add(a, b):
    """Takes in two numbers, returns their sum."""
    return a+b

print("Using __doc__:")
print(add.__doc__)
  
print("Using help:")
help(add)

Output:

Using __doc__:
Takes in two numbers, returns their sum.
Using help:
Help on function add in module __main__:

add(a, b)
    Takes in two numbers, returns their sum.

Using triple single quotes

def product(a, b):
    '''Takes in two numbers, returns their product.'''
    return a*b

print("Using __doc__:")
print(product.__doc__)
  
print("Using help:")
help(product)

Output:

Using __doc__:
Takes in two numbers, returns their product.
Using help:
Help on function product in module __main__:

product(a, b)
    Takes in two numbers, returns their product.

One-line Docstring

It fits in one line. The closing quotes are on the same line as the opening quotes.

def power(a, b):
    """Returns a raised to power b."""
    return a**b
  
print(power.__doc__)

Output:

Returns a raised to power b.

Multi-line Docstring

It is consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. 

def add(a, b):
    '''
        Returns the sum of two  numbers.

            Parameters:
                a (int): A integer
                b (int): Another integer

            Returns:
                sum (int):The sum of a and b
    '''
    sum=a+b
    return sum

print(add.__doc__)

Output:

   Returns the sum of two  numbers.

            Parameters:
                    a (int): A integer
                    b (int): Another integer

            Returns:
                    sum (int):The sum of a and b
Tags
Submitted by devanshi.srivastava on June 15, 2021

Devanshi, is working as a Data Scientist with iVagus. She has expertise in Python, NumPy, Pandas and other data science technologies.

About

At ProgramsBuzz, you can learn, share and grow with millions of techie around the world from different domain like Data Science, Software Development, QA and Digital Marketing. You can ask doubt and get the answer for your queries from our experts.