added much more detailed documentation