improved comments and fix to wrong variable name in return

Hat tip to @rixbeck for spotting this in https://github.com/bolt/bolt/issues/1486