made another pass through the API docs clarifying and adding example cod...

...e