Added basic comment descriptions to the scripts and to some of the source files. There's still much to be done, but it's a start.

amodem/alsa.py

@@ -3,6 +3,9 @@ import logging
 
 log = logging.getLogger(__name__)
 
+"""Code which adds Linux ALSA support for interfaces, 
+recording and playing.
+"""
 
 class Interface(object):
 

amodem/async.py

@@ -4,6 +4,8 @@ import logging
 
 log = logging.getLogger()
 
+"""Asynchronous Reading capabilities for amodem.
+"""
 
 class AsyncReader(object):
     def __init__(self, stream, bufsize):

amodem/audio.py

@@ -4,6 +4,8 @@ import time
 
 log = logging.getLogger(__name__)
 
+"""Audio capabilities for amodem.
+"""
 
 class Interface(object):
     def __init__(self, config, debug=False):

amodem/calib.py

@@ -10,6 +10,8 @@ import subprocess
 
 log = logging.getLogger(__name__)
 
+"""Calibration capabilities for amodem.
+"""
 
 def volume_controller(cmd):
     def controller(level):

amodem/common.py

@@ -9,6 +9,8 @@ log = logging.getLogger(__name__)
 
 scaling = 32000.0  # out of 2**15
 
+"""Commom utilities and procedures for amodem.
+"""
 
 def load(fileobj):
     ''' Load signal from file object. '''

amodem/detect.py

@@ -9,6 +9,8 @@ import collections
 
 log = logging.getLogger(__name__)
 
+"""Signal detection capabilities for amodem.
+"""
 
 class Detector(object):
 

amodem/dsp.py

@@ -2,6 +2,8 @@ import numpy as np
 
 from . import common
 
+"""Digital Signal Processing capabilities for amodem.
+"""
 
 class FIR(object):
     def __init__(self, h):

amodem/equalizer.py

@@ -5,6 +5,8 @@ from . import levinson
 import numpy as np
 import itertools
 
+"""Audio equalizing capabilities for amodem.
+"""
 
 class Equalizer(object):
 

scripts/plot.py

@@ -5,6 +5,10 @@ from amodem import common
 from amodem.config import Configuration
 import sys
 
+"""Script that exposes pylab's spectogram plotting
+capabilities to the command line. It implements this
+for amodem.config Configurations.
+"""
 
 def spectrogram(t, x, Fs, NFFT=256):
     ax1 = pylab.subplot(211)

scripts/record.py

@@ -3,6 +3,9 @@ import argparse
 from amodem import audio
 from amodem.config import Configuration
 
+"""Script that records audio through an interface
+and stores it into an amodem.config Configuration.
+"""
 
 def run(args):
     config = Configuration()

scripts/resample.py

@@ -3,6 +3,11 @@ from amodem.sampling import resample
 import argparse
 import sys
 
+"""Script that exposes the amodem.resample() function 
+to the command line, taking parameters via standard 
+inputs and returning results via standard outputs.
+"""
+
 
 def main():
     p = argparse.ArgumentParser()