Documentation updates

Ready file now contains many useful examples.
PHPdoc fixes to some methods.