Function documentation strings in Python

Function documentation strings

print(map.__doc__)

Output:

map(func, *iterables) --> map object

Make an iterator that computes the function using arguments from
each of the iterables.  Stops when the shortest iterable is exhausted.

Process finished with exit code 0

Now, let's see the docstring for collections module.

print(map.__doc__)
import collections
print(collections.__doc__)

Output:

map(func, *iterables) --> map object

Make an iterator that computes the function using arguments from
each of the iterables.  Stops when the shortest iterable is exhausted.
This module implements specialized container datatypes providing
alternatives to Python's general purpose built-in containers, dict,
list, set, and tuple.

* namedtuple   factory function for creating tuple subclasses with named fields
* deque        list-like container with fast appends and pops on either end
* ChainMap     dict-like class for creating a single view of multiple mappings
* Counter      dict subclass for counting hashable objects
* OrderedDict  dict subclass that remembers the order entries were added
* defaultdict  dict subclass that calls a factory function to supply missing values
* UserDict     wrapper around dictionary objects for easier dict subclassing
* UserList     wrapper around list objects for easier list subclassing
* UserString   wrapper around string objects for easier string subclassing

Process finished with exit code 0

As you can see, this generates a documentation text for the module, as well as a description of the various classes accessible inside that module. And what I really like about this feature is that I can learn about various Python APIs interactively as I need to without having to rely on lengthy documentation. It's also a simple template for other developers to use when creating their own packages and modules. To accomplish this for your functions and other code, simply look for a literal string at the start of a function, class, or module.

There are several recommended practices you should adhere to. So, let's look at a few of them.

1- Even though the docstring is only one line long, it should always be contained in triple quotes. This makes it simple to build on later.

2- Your docstring's first line should summarize the function, class, or module and its primary purpose.

3- Modules: List the relevant classes and sub-modules present within packages and modules, as well as any custom exceptions that the developer should be aware of.

4- Classes: List the key methods for classes, as well as any enums, static member functions, or attributes that the class supports. There are several crucial factors to consider when it comes to functions.