Public documentation enhancement and update.
Includes minor internal documentation fixes in place linked to from the public part