extract complete API docs

Provide more details, examples, and reasoning for the entire API.