added some docs and convenience function