add some new functions; document everything