document API with usage examples, etc