Bug 483743: Document use of multiple sets of null annotationsI20160202-1000I20160202-0800I20160128-2000I20160127-2000I20160127-0800I20160126-2000

3 files changed, 32 insertions, 7 deletions

diff --git a/bundles/org.eclipse.jdt.doc.user/reference/preferences/java/compiler/ref-preferences-errors-warnings.htm b/bundles/org.eclipse.jdt.doc.user/reference/preferences/java/compiler/ref-preferences-errors-warnings.htm
index f18d53d44..7e6b74843 100644
--- a/bundles/org.eclipse.jdt.doc.user/reference/preferences/java/compiler/ref-preferences-errors-warnings.htm
+++ b/bundles/org.eclipse.jdt.doc.user/reference/preferences/java/compiler/ref-preferences-errors-warnings.htm
@@ -1049,10 +1049,15 @@
 			</li>
 			<li>
 				<b>org.eclipse.jdt.annotation.NonNullByDefault</b>: A fully qualified name of a Java annotation type. When applied to an element without an annotation argument, 
-				all unannotated types in method signatures within the annotated element will be treated as if they were specified with the non-null annotation.<br>
-				On the contrary, when the annotation is applied with the constant 'false' as its argument, all corresponding defaults at outer scopes will be canceled for the annotated element.
+				all unannotated types in method signatures and field declarations within the annotated element will be treated as if they were specified with the non-null annotation.<br>
+				Only when using the default annotation type <code>org.eclipse.jdt.annotation.NonNullByDefault</code>, also the opposite effect is supported:
+				When the annotation is applied with the constant 'false' as its argument (or '{}' in the case of type annotations),
+				all corresponding defaults at outer scopes will be canceled for the annotated element.
 			</li>
 		</ul>
+		<p>The compiler supports exactly one <em>primary</em> set of annotation types for null specification. Additionally, an arbitrary number of <em>secondary</em> annotation types
+		can be configured to carry the same semantics. Secondary annotation types are supported for the sole purpose of interfacing with 3rd party code that is already specified
+		using other null annotations than the primary annotations types of the current project.</p>
 		</td>
 		<td valign="top">
 		<p>On</p>
diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm
index 960446fb6..ca8c57b88 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm
@@ -79,7 +79,7 @@ for its enhanced null analysis (which is disabled by default):
 <ul>

 <li><code>@NonNull</code>: null is not a legal value</li>

 <li><code>@Nullable</code>: null value is allowed and must be expected</li>

-<li><code>@NonNullByDefault</code>: types in method signatures

+<li><code>@NonNullByDefault</code>: types in method signatures and field declarations

 	that lack a null annotation are regarded as non-null.</li>

 </ul>

 <p>Annotations <code>@NonNull</code> and <code>@Nullable</code> are supported in these locations:</p>

@@ -93,16 +93,17 @@ for its enhanced null analysis (which is disabled by default):
 <p><code>@NonNullByDefault</code> is supported for</p>

 <ul>

 <li>Methods - to affect all types in this method's signature</li>

-<li>Types (classes, interfaces, enums) - to affect all methods in the type body</li>

+<li>Types (classes, interfaces, enums) - to affect all methods and fields in the type body</li>

 <li>Package (via a file <code>package-info.java</code>) - to affect all types in the package</li>

 </ul>

 <p>

 Note, that even the actual qualified names of these annotations are 

 <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_annotation_names">configurable</a>,

 but by default the ones given above are used (from the package <code>org.eclipse.jdt.annotation</code>).

-When using 3rd party null annotations, please ensure that those are properly defined using at least a <code>@Target</code>

+When using 3rd party null annotation types, please ensure that those are properly defined using at least a <code>@Target</code>

 meta annotation, because otherwise the compiler can not distinguish between declaration annotations (Java 5)

-and type annotations (Java 8). 

+and type annotations (Java 8). Furthermore, some <a href="#cancel_default">details of <code>@NonNullByDefault</code></a> are not supported when using

+3rd party annotation types (see <a href="task-using_null_type_annotations.htm#compatibility_semantics">here</a> for the Java 8 variant). 

 </p>

 

 <h2 id="buildpath_setup">Setup of the build path</h2>

@@ -260,7 +261,7 @@ In this situation you will be forced to omit null annotations
 (<em>plans exist to support adding annotations to libraries after-the-fact, but no promise can be made yet,

 if and when such a feature will be available</em>).

 </p>

-<h3>Canceling a nullness default</h3>

+<h3 id="cancel_default">Canceling a nullness default</h3>

 <p>The situation will get tricky, if a sub-type of a "legacy" type resides in a package for which 

 <code>@NonNullByDefault</code> has been specified. Now a type with an un-annotated super-type

 would need to mark all parameters in overriding methods as <code>@Nullable</code>:

@@ -290,6 +291,9 @@ class MyClass extends LegacyClass {
     }

 }

 </pre>

+<p>Canceling a nullness default may not be possible when using annotation types other than

+<code>org.eclipse.jdt.annotation.NonNullByDefault</code> supplied by Eclipse,

+because other annotation types may not declare the boolean property that is used here.</p>

 <h3 id="fields">The case of fields</h3>

 <p>Null annotations work best when applied in <b>method signatures</b> (<b>local variables</b>

 typically don't even need these, but may also leverage null annotations for bridging between

diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm
index fd5bb3eec..a8ea2291f 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm
@@ -46,6 +46,16 @@ are enabled).
 Users <em>migrating</em> from null annotations in previous versions to Java-8-style

 null type annotations are advised to check the section about <a href="#compatibility">compatibility</a>.

 </p>

+<p>

+Note, that the actual qualified names of null type annotations are 

+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_annotation_names">configurable</a>,

+but by default the ones shown here are used (from the package <code>org.eclipse.jdt.annotation</code>).

+When using 3rd party null annotation types, please ensure that those are properly defined using at least a <code>@Target</code>

+meta annotation, because otherwise the compiler can not distinguish between declaration annotations (Java 5)

+and type annotations (Java 8). Furthermore, some <a href="#compatibility_semantics">details of <code>@NonNullByDefault</code></a>

+are not supported when using 3rd party annotation types. 

+</p>

+

 

 <h2 id="generics">Generics</h2>

 Perhaps the main advantage of type annotations for null analysis is the ability to annotate

@@ -390,6 +400,7 @@ Require-Bundle: ...,
 While the fundamental semantics of null annotation remains unchanged,

 the annotation <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"

 	><code>@NonNullByDefault</code></a> has been changed slightly:

+</p>

 <ul>

 <li>This annotation can now affect more locations.</li>

 <li>The locations to be affected can be fine tuned using the 

@@ -404,6 +415,11 @@ the annotation <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/e
 </table>

 </li>

 </ul>

+<p>

+Note, that the <code>value</code> property described here is only supported when using the annotation type

+<code>org.eclipse.jdt.annotation.NonNullByDefault</code> supplied by Eclipse.

+</p>

+<p>

 Although the Java 8 variant of

 	 <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"

 	><code>@NonNullByDefault</code></a> affects more locations, two noteworthy exceptions exist