**What is Docstring?**

In Python, a docstring is a string literal that appears right after the definition of a function, method, class, or module. It’s a way of documenting our code, and it’s completely different from comments.

```
def square(n):
'''Takes in a number n, returns the square of n'''
return n**2
```

**Difference from Comments**

While comments are ignored by the Python interpreter, **docstrings are retained throughout the runtime of the program.**

This means we can access these docstrings using** the __doc__ attribute**, which can be incredibly useful for understanding the purpose and functionality of any function, method, or class.

**How to Write Docstrings**

**1. Single Line Docstrings**

Single line docstrings are concise explanations of an object’s purpose.

They are written within triple quotes, even though they are single-lined.

```
def square(n):
'''Takes in a number n, returns the square of n'''
return n**2
```

This is because they can be expanded easily later. The closing quotes are on the same line as the opening quotes.

**2. Multi Line Docstrings**

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

They are used when the object described is more complex.

```
def add_binary(a, b):
'''
Returns the sum of two decimal numbers in binary digits.
Parameters:
a (int): A decimal integer
b (int): Another decimal integer
Returns:
binary_sum (str): Binary string of the sum of a and b
'''
binary_sum = bin(a+b)[2:]
return binary_sum
```

**How to Write Docstrings in ****

**in Python Functions**

For functions, the docstring should clearly explain the function’s purpose, its arguments, and its return value.

If the function raises any exceptions, those should be documented as well.

```
def add_numbers(a, b):
"""
Adds two numbers together.
Parameters:
a (int): The first number to add.
b (int): The second number to add.
Returns:
int: The sum of a and b.
"""
return a + b
```

In this example, the docstring explains what the function does (“Adds two numbers together.”), the parameters it takes (a and b, both integers), and what it returns (the sum of a and b, an integer).

**in Python Classes**

For classes, the docstring should provide a brief overview of the class, its methods, and its instance variables.

```
class MyClass:
"""
A simple example class.
Attributes:
attr1 (int): Description of attr1.
attr2 (str): Description of attr2.
Methods:
method1: Description of method1.
method2: Description of method2.
"""
def __init__(self, attr1, attr2):
"""
Initializes MyClass with attr1 and attr2.
Parameters:
attr1 (int): Description of attr1.
attr2 (str): Description of attr2.
"""
self.attr1 = attr1
self.attr2 = attr2
def method1(self):
"""
Description of method1.
"""
pass
def method2(self):
"""
Description of method2.
"""
pass
```

In this example, the class docstring provides an overview of the class, its attributes (attr1 and attr2), and its methods (method1 and method2).

The `__init__`

method also has its own docstring explaining its parameters.

**in Python Modules**

For modules, the docstring should provide a high-level overview of the module’s purpose and contents.

```
"""
This is an example module.
This module demonstrates the creation of functions, classes, and variables.
Functions:
function1: Description of function1.
function2: Description of function2.
Classes:
Class1: Description of Class1.
Class2: Description of Class2.
Variables:
var1: Description of var1.
var2: Description of var2.
"""
```

In this example, the module docstring provides an overview of the module and lists its functions, classes, and variables.

Remember, the goal of a docstring is to help others (and your future self) understand your code, so make sure they’re clear, concise, and helpful!

**Useful Usages**

We can access the docstrings of any object using **the __doc__ attribute**. This can be incredibly useful for understanding the purpose and functionality of any function, method, or class.

We can also use **the help() function** to read the docstrings associated with various objects.

**Recommended PEP8 Rules**

PEP 257 provides the standard conventions to write docstrings for various objects.

**1. First Line**

The first line of your docstring should be a concise summary of the function’s purpose.

```
def square(n):
"""Returns the square of a number."""
return n**2
```

In this example, the docstring is a brief, clear statement that describes what the function does.

**2. Multi-line Docstrings**

If your docstring is going to span multiple lines, the first line should still be a summary, similar to a one-liner. The following lines should be a more detailed description of the function.

```
def square(n):
"""
Returns the square of a number.
This function takes a number as input, squares it, and returns the result.
"""
return n**2
```

In this example, the first line is a brief summary, and the following lines provide a more detailed description of what the function does.

**3. Indentation**

The indentation of your docstring should match that of the quotes at the start of the docstring.

```
def square(n):
"""
Returns the square of a number.
This function takes a number as input, squares it, and returns the result.
"""
return n**2
```

In this example, the docstring is indented to align with the quotes that start the docstring.

**4. Blank Lines**

According to PEP8, there should be a blank line before the end of a multi-line docstring.

```
def square(n):
"""
Returns the square of a number.
This function takes a number as input, squares it, and returns the result.
"""
return n**2
```

In this example, there is a blank line between the end of the docstring and the closing quotes.

**5. Quotation Marks**

Docstrings should be enclosed in triple double quotes. For example:

```
def square(n):
"""Returns the square of a number."""
return n**2
```

In this example, the docstring is enclosed in triple double quotes.