Improve documentation

[OWissett]

We need to have good documentation across all of the public functions and data structures.

We should have something like this:

/// Some short descriptive title
///
/// ## Overview
///  more details....
/// 
///  ## Arguments
...

/// ## Panics (if appropriate)
...

/// ## Errors (if appropriate)

/// # Returns

///

All need to have a brief description and a good overview, maybe including an example.

The arguments and returns values should be described.

If a function can panic or return an error, then these should be documented.

If a public function is unsafe this needs to be documented - and potentially should be hidden behind a feature flag.