this module is not particularly self-descriptive.  A brief file-level doc comment would go a long way even if we don't go deep on other docs.