Documentation

The two main elements of Python documentation are:

Inline documentation

Inline documentation can in principle be placed anywhere in the code; it is indicated

by the use of one or more leading hash characters (#). In general, there should be at

least two spaces before a hash.

Documentation strings

Such strings are used to provide documentation for Python functions (methods) and

classes, and are generally placed within their definition (at the beginning of the

indented code).

The code in Example A-2 contains multiple examples of inline documentation.

Example A-4 shows the same function definition as in Example A-3, but this time with a

documentation string added.

Example A-4. The Python function is_prime with documentation string

Function to check prime characteristic of integer

is_prime_with_doc.py

def is_prime(I):
”’ Function to test for prime characteristic of an integer.

            Parameters

            ==========

            I   :   int

                            number  to  be  checked for prime   characteristc



            Returns

            =======

            output: string

                            states  whether number  is  prime   or  not;

                            if  not,    provide a   prime   factor



            Raises

            ======

            TypeError

                            if  argument    is  not an  integer

            ValueError

                            if  the integer is  too small   (2  or  smaller)



            Examples

            ========

            >>> is_prime(11)

            Number  is  prime.

            >>> is_prime(8)

            Number  is  even,   therefore   not prime.

            >>> is_prime(int(1e8    +   7))

            Number  is  prime.

            >>>

            ”’

if type(I) != int:
raise TypeError(“Input has not the right type.”)
if I <= 3 :
raise ValueError(“Number too small.”)
else:
if I % 2 == 0 :
print “Number is even, therefore not prime.”
else:
end = int(I / 2.) + 1