[doc] document some of the API