Clarify the overall philosophy of the module and divide up docs between define() and the parse_* functions. Adds a note about doubled log messages. Fixes #1866