clarify some docs
added some helper methods