Clarify the interface

[djs55]

The interface between this library and other libraries and programs is currently unclear. I suggest we start fixing this by:

• auto-generate an .mli
• move the obviously .mli comments from the .ml into the .mli
• experimentally hide functions and see if opam downstream packages still build, hide function if so
• study code and cook up some docs for the remaining undocumented functions
• review the result and see if it needs further refactoring