Update AccountManager's javadoc.
Includes several potentially controversial major changes:
- Remove the amount of repeated boilerplate explanations of common
idioms. I find them much more distracting than useful. The same
things are explained, but in fewer places.
- Add more narrative/directive information instead of merely descriptive
commentary; I included a lot of "color" about who particular methods are
intended for and why you might use them.
- Add explicit guidance (in the class javadoc) about the common usage pattern.
Explicitly document the auth token invalidation dance, which is highly
nonobvious, had never been written down before, and which GMM got wrong,
creating a Latitude conops nightmare they're still digging out of.
- Explain and justify, as best I can, the overall model of account management:
saved credentials, pluggable authenticators, auth tokens, and so on. Clarify
some things, like that setPassword() changes the locally cached credential
but does not set the user's password on the server.
- Clarify what the passed-in Activity parameter is used for. (It seems silly,
but I was confused by this: is it supposed to be the Activity that actually
performs the password prompt or whatever? No, it's just a Context for the
startActivity() to be launched from.)
1 file changed