inaccurate documentation is worse than no documentation at all

also, just writing this out makes it clear there's some cleanup to do in the api