Documentation for bug 388281 - [compiler][null] inheritance of nullv20121202-154322I20121210-0800I20121209-2000I20121204-2230I20121204-1600I20121204-1000I20121204-0915I20121204-0800

annotations as an option

4 files changed, 72 insertions, 4 deletions

diff --git a/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_options.htm b/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_options.htm
index 989e229a1..e8c87f80f 100644
--- a/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_options.htm
+++ b/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_options.htm
@@ -134,9 +134,15 @@ parentheses and the default value is shown in bold italics.</p>
   <a href=
 "../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_PB_NULL_SPECIFICATION_VIOLATION">COMPILER_PB_NULL_SPECIFICATION_VIOLATION</a>,
   <a href=
-"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_PB_NULL_ANNOTATION_INFERENCE_CONFLICT">COMPILER_PB_NULL_ANNOTATION_INFERENCE_CONFLICT</a> and
+"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_PB_NULL_ANNOTATION_INFERENCE_CONFLICT">COMPILER_PB_NULL_ANNOTATION_INFERENCE_CONFLICT</a>,
   <a href=
-"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_PB_NULL_UNCHECKED_CONVERSION">COMPILER_PB_NULL_UNCHECKED_CONVERSION</a>.</p></td>
+"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_PB_NULL_UNCHECKED_CONVERSION">COMPILER_PB_NULL_UNCHECKED_CONVERSION</a>,
+  <a href=
+"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_PB_REDUNDANT_NULL_ANNOTATION">COMPILER_PB_REDUNDANT_NULL_ANNOTATION</a>,
+  <a href=
+"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_PB_MISSING_NONNULL_BY_DEFAULT_ANNOTATION">COMPILER_PB_MISSING_NONNULL_BY_DEFAULT_ANNOTATION</a> and
+  <a href=
+"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_INHERIT_NULL_ANNOTATIONS">COMPILER_INHERIT_NULL_ANNOTATIONS</a>.</p></td>
 <td><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#ENABLED">ENABLED</a></b></td>
 </tr>
 <tr valign="top">
@@ -269,6 +275,30 @@ elements.</td>
 <td><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#DISABLED">DISABLED</a></b></td>
 
 </tr>
+
+<tr>
+<td colspan="2"><b>Inheritance of Null Annotations</b> (<b><a href=
+"../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_INHERIT_NULL_ANNOTATIONS">COMPILER_INHERIT_NULL_ANNOTATIONS</a></b>)</td>
+</tr>
+<tr valign="top">
+<td rowspan="2">When enabled, the compiler will check for each method without any explicit null annotations
+	 (see <a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_ANNOTATION_NULL_ANALYSIS">COMPILER_ANNOTATION_NULL_ANALYSIS</a>):
+	 If it overrides a method which has null annotations, it will treat the
+	 current method as if it had the same annotations as the overridden method.
+	 <p>Annotation inheritance will use the <em>effective</em> nullness of the overridden method
+	    after transitively applying inheritance and after applying any default nullness
+	    (see <a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_NONNULL_BY_DEFAULT_ANNOTATION_NAME">COMPILER_NONNULL_BY_DEFAULT_ANNOTATION_NAME</a>) 
+	    at the site of the overridden method.</p>
+	 <p>If different implicit null annotations (from a nonnull default and/or overridden methods) are applicable
+	    to the same type in a method signature, this is flagged as an error 
+	    and an explicit null annotation must be used to disambiguate.</p></td>
+<td><b><a href=
+"../reference/api/org/eclipse/jdt/core/JavaCore.html#ENABLED">ENABLED</a></b></td>
+</tr>
+<tr valign="top">
+<td><b><i><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#DISABLED">DISABLED</a></i></b></td>
+</tr>
+
 <tr>
 <td colspan="2"><b>Generating Line Number Debug Attribute</b> (<b><a href=
 "../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_LINE_NUMBER_ATTR">COMPILER_LINE_NUMBER_ATTR</a></b>)</td>
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 1e90ab172..66183e5c5 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
@@ -1017,6 +1017,25 @@ use raw types in the first place.</p>
 		<p>On</p>
 		</td>
 	</tr>
+	<tr id="inherit_null_annotations">
+		<td valign="top" style="padding-left: 2em;">
+		<p>Inherit null annotations</p>
+		</td>
+		<td valign="top">
+		<p>When enabled, the compiler will check for each method without any explicit null annotations:
+	 	  If it overrides a method which has null annotations, it will treat the
+	 	  current method as if it had the same annotations as the overridden method.</p>
+	 	  <p>Annotation inheritance will use the <em>effective</em> nullness of the overridden method
+	 		after transitively applying inheritance and after applying any default nullness
+	 		at the site of the overridden method.</p>
+	 	  <p>If different implicit null annotations (from a nonnull default and/or overridden methods) are applicable
+	 		to the same type in a method signature, this is flagged as an error 
+	 		and an explicit null annotation must be used to disambiguate.</p>
+		</td>
+		<td valign="top">
+		<p>Off</p>
+		</td>
+	</tr>
 </table>
 
 <p>When <strong>Treat above errors like fatal compile errors</strong> is enabled, all generated errors, fatal or configurable, lead to non-executable code.
diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm
index d46bce512..64e7e6080 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm
@@ -216,7 +216,7 @@ In <span class="c3">1.4</span>, <span class="c3"><i>assert</i></span> is treated
 <td colspan="3">Display advanced warning options</td>
 </tr>
 <tr>
-<td valign="top" width="250" rowspan="98"><a name="warn">-warn:...</a></td>
+<td valign="top" width="250" rowspan="99"><a name="warn">-warn:...</a></td>
 
 <!-- !!! YOU MUST ADJUST THE rowspan IF YOU ADD/REMOVE A -warn SUB-OPTION !!! -->
 
@@ -403,6 +403,11 @@ will enable more warnings than the default, and specifying "-" disables some tha
 <td valign="top">indirect reference to static member</td>
 </tr>
 <tr>
+<td align="center" valign="top">-</td>
+<td align="left" valign="top">inheritNullAnnot</td>
+<td valign="top">consider null annotations as being inherited from an overridden method to any overriding methods</td>
+</tr>
+<tr>
 <td align="center" valign="top">+</td>
 <td align="left" valign="top">intfAnnotation</td>
 <td valign="top">annotation type used as super interface</td>
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 e6ea72e9d..4d6c78471 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
@@ -117,7 +117,10 @@ There are two quick fixes on unresolved references to <code>@NonNull</code>, <co
 <p><img src="images/task-null-annotations-qf-bundle.png" alt="Add library with default null annotations to build path"></p>

 </li>

 </ul> 

-

+<p>

+When manually configuring the build path for a OSGi bundle / plug-in, it is recommended to set an <code>additional.bundles</code> entry

+in file <code>build.properties</code> to avoid an undesired runtime dependency.

+</p>

 <h2 id="interpretation_of_null_annotations">Interpretation of null annotations</h2>

 <p>

 It should be clear now that null annotations add more information to your

@@ -193,6 +196,17 @@ Interestingly, the reverse redefinitions are legal: adding a <code>@Nullable</co
 or a <code>@NonNull</code> return annotation (you may consider these as "improvements" of the method,

 it accepts more values and produces a more specific return value).

 </p>

+<p>By forcing sub-classes to repeat null annotations in any overriding methods, the null contract of

+each method can be understood without searching the inheritance hierarchy. However, in situations

+where an inheritance hierarchy mixes code of different provenance it may not be possible to add

+null annotations to all classes at once. In these situations the compiler can be told to treat

+methods with missing null annotations as if annotations from an overridden method were <strong>inherited</strong>.

+This is enabled using the compiler option 

+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#inherit_null_annotations">inherit null annotations</a>.

+It is possible that a method overrides two methods with different null contracts. Also a nullness default

+can be applicable at a method which is in conflict with an inherited null annotation.

+These cases are flagged as an error and the overriding method must use an explicit null annotation to resolve the conflict.

+</p> 

 <h3>Legacy super-types</h3>

 <p>

 The previous considerations add a difficulty when annotated code is written as a sub-type