[doc] document the API