(docs) add comments to util functions