add comments around API