Improve is_anonymous docs to warn about Zope security model in __init__

We just came by this issue this morning (change getAuthenticatedUser to is_anonymous):

https://stackoverflow.com/questions/8254521/portal-membership-getauthenticateduser-portal-state-member-etc-always-return

I'm making a View with customized traversal. I want to traverse to next object dynamically base on current logged in user. But all method I know (portal_membership.getAuthenticatedUser, portal_state.member etc..) always return anonymous on View object's init and publicTraversal. The only case they return right is in object's call. What should I do to make getAuthenticatedUser work on my case (either on view's init or publicTraversal call)?

@mjpieters gave an impecable answer:

You can't. Due to Zope's security model, the user is determined after traversal, because this information depends on the context of the published object. You can only rely on getAuthenticatedUser when the object is being published; after traversal, authentication and authorization take place, and then publication, which in views means invoking the call method. Because publicTraversal is called as part of the traversal stage, you cannot know the authenticated user in that method either. You'll have to re-think your view to not rely on the authenticated user being known during that stage.

Since this is at Zope level and trying to add a WARNING or something like that when we're trying to get the user in __init__ is not possible, would it be the case to at least add a warning to plone.api docs (and the method docstring as well) and portal_membership method itself?

Start with the is_anonymous documentation and method docstring in plone.api, then inspect the portal_membership method mentioned in the issue. Document that the authenticated user is unavailable during init and publicTraversal because authentication follows traversal, while call can rely on it. Done means the warning is present in the relevant API documentation and docstrings.