add roxygen comments to some helper methods (more consistent and readable IMHO)