IMHO, because the API is confusing, the methods should properly be explicitly explained in the module's documentation—even those methods that, to an experienced computer programmer, seem plainly obvious from their names alone.

Make a request via perlbug. Increase the likelihood of your request being applied by submitting a patch.