Some small improvements (hopefully !) to the code documentation and variable descriptions. Implements #208 (closed).