add function comments and compact some lines
fix comment, added test (that doesn't work)