document and some interface refinement