The last part of the class javadoc for AccessController where it
gives an example of using the version of doPrivileged() that takes
an AccessControlContext parameter is misleading.

It says:

 * <p> There are also times where you don't know a priori which permissions
 * to check the context against. In these cases you can use the
 * doPrivileged method that takes a context:
 *
 * <pre>
 * somemethod() {
 * AccessController.doPrivileged(new PrivilegedAction() {
 * public Object run() {
 * // Code goes here. Any permission checks from this
 * // point forward require both the current context and
 * // the snapshot's context to have the desired permission.
 * }
 * }, acc);
 * ...normal code here...
 * }
 * </pre>


The comment that says "Code goes here..." says the access
control context is intersected with the "current context". This is
false. "Current context" sounds like it is the same thing as
the result of calling getContext() but this is not the case. Instead
it is only the protection domain of the caller of doPrivileged() which
is intersected with the 2nd parameter ACC.

The actual method-specific javadoc is correct but these
class-level comments could confuse someone writing security-sensitive
code.