Update the documentation to match the current behavior. As noted in
https://github.com/hypothesis/client/pull/6638, the code comments and behavior
were inconsistent. Since changing the behavior is potentially disruptive, that
PR changed the comments instead. This commit updates the publisher-facing
documentation.