added perlimenary documentation to some functions