Reconcile C API with docs

This fixes #5286 and results from discussion on that issue.