In the previous sessions you learned how to package code into functions and to package functions into modules (also called libraries). Functions and modules let you easily design, write and package your code so that it is easy to understand and easily reusable. However, to share the code and to provide information detailing how the code works and what it does, you need to add documentation.
You have already seen documentation using python
help(). For example, lets look at the documentation for the
sys module that have used. To do this, start a new
ipython session and type;
import sys help(sys)
You should see printed;
Help on built-in module sys: NAME sys FILE (built-in) MODULE DOCS http://docs.python.org/library/sys DESCRIPTION This module provides access to some objects used or maintained by the interpreter and to functions that interact strongly with the interpreter. Dynamic objects: argv -- command line arguments; argv is the script pathname if known path -- module search path; path is the script directory, else '' modules -- dictionary of loaded modules
q to exit the help)
Now, assuming that you have a copy of checkmain.py in your current directory, you can compare this documentation to the documentation for the
checkmain script that we wrote in the last session. Type;
import checkmain help(checkmain)
This should print something like;
Help on module checkmain: NAME checkmain FILE /path/to/checkmain.pyc FUNCTIONS addArrays(x, y)
While better than nothing, this is not great. It is very important when programming in any language that we provide full documentation for all of the functions and modules. In python, this is achieved by adding documentation strings to each part of the script. These are strings that are placed at the beginning of the function or module. For example, into your open
ipython session, type;
def documentedFunction(a): """Here is the documentation string for this function""" return a help(documentedFunction)
You should see printed to the screen;
Help on function documentedFunction in module __main__: documentedFunction(a) Here is the documentation string for this function
"""checkmain is a simple python script to demonstrate hiding the code if the script is imported as a module""" def addArrays(x, y): """This function adds together each element of the two passed lists, returning the result in the returned list.""" z =  for i in range(0,len(x)): z.append( x[i] + y[i] ) return z if __name__ == "__main__": # Don't run this code if this script is being # imported as a module a = [ 1, 2, 3, 4 ] b = [ 5, 6, 7, 8 ] c = addArrays(a, b) print( c )
Now start a new
ipython session in the same directory as your new
checkmain.py script and type;
ipython import checkmain help(checkmain)
You should now see printed;
Help on module checkmain: NAME checkmain FILE /path/to/checkmain.pyc DESCRIPTION checkmain is a simple python script to demonstrate hiding the code if the script is imported as a module FUNCTIONS addArrays(x, y) This function adds together each element of the two passed lists, returning the result in the returned list.
The documentation strings that were enclosed in three pairs of double quotes, e.g.
"""documentation string""", are correctly added to the right parts of the documentation in python’s
help. All you need to do is just ensure that you add a documentation string at the top of every script, and at the start of every function.
Edit your morse.py script and add documentation strings for the module and also for all of the functions.
If you are really stuck then here is an example