--- old/src/java.compiler/share/classes/javax/lang/model/element/package-info.java 2016-08-19 15:50:16.876257448 -0700 +++ new/src/java.compiler/share/classes/javax/lang/model/element/package-info.java 2016-08-19 15:50:16.792257445 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -53,7 +53,9 @@ * Names of parameters may not be recoverable from class files. * * The {@linkplain javax.lang.model.element.Modifier modifiers} on an - * element may differ in some cases including: + * element created from a class file may differ in some cases from an + * element for the same declaration created from a source file + * including: * * * - * Additionally, synthetic constructs in a class file, such as - * accessor methods used in implementing nested classes and bridge - * methods used in implementing covariant returns, are translation - * artifacts outside of this model. + * Some elements which are {@linkplain Elements.Naturalness#MANDATED + * mandated} may not be marked as such when created from class files. + * + * Additionally, {@linkplain Elements.Naturalness#SYNTHETIC synthetic} + * constructs in a class file, such as accessor methods used in + * implementing nested classes and {@linkplain + * Elements#isBridge(Element) bridge methods} used in implementing + * covariant returns, are translation artifacts strictly outside of + * this model. However, when operation on class files, it is helpful + * be able to operate on such elements, screening them out when + * appropriate. * *

During annotation processing, operating on incomplete or * erroneous programs is necessary; however, there are fewer