Heck, "better" isn't even necessary, crappy, but correct would be adequate. When the docs make multiple mutually disagreeing, statements regarding function parameter requirements, none of which are actually correct, and then point the reader to an example case at hasn't been valid for several releases, even /no/ documentation would be an improvement. At least then we wouldn't go down the garden path of thinking that it was possible to use, without more work than a complete rewrite.