added some docs (library design)