Improve documentation of the authentication infrastructure.

It was _intentional_, if that's what you're asking. My intention was to remove the only use before / when adding the deprecation notice. I can revert this if there's a difference between the two implementations I'm not aware of …