api: adding missing examples, and editing reference docs