Bug 574603 - [null][external] offer more IDE options for specifying
external annotation locations
user documentation
Change-Id: I1160c0160460068b462bb5c35eec3f1a0b7b6f01
Reviewed-on: https://git.eclipse.org/r/c/platform/eclipse.platform.common/+/183349
Tested-by: Stephan Herrmann <stephan.herrmann@berlin.de>
Reviewed-by: Stephan Herrmann <stephan.herrmann@berlin.de>
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 2bfa829..bf9fa33 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
@@ -1184,6 +1184,21 @@
<p>Off</p>
</td>
</tr>
+ <tr id="external_annotations_from_all_locations">
+ <td valign="top" style="padding-left: 2em;">
+ <p>Search for external annotations in all build path locations</p>
+ </td>
+ <td valign="top">
+ <p>When enabled, the compiler will search all build path locations for
+ <a href="../../../../tasks/task-using_external_null_annotations.htm">external annotations</a> to be considered
+ during annotation-based null analysis. This strategy will be applied to every class file found during compilation.
+ <br>The default is to search only those locations that are specified using the "external annotations" property
+ of each individual build path entry and apply any annotations found only to classes in that corresponding build path entry.</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_external_null_annotations.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm
index 410ce82..9200ec9 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm
@@ -61,6 +61,13 @@
to use the same external annotation location for all projects referring to the same library.
A shared ("common") base project will typically be a good choice for hosting external annotations.
</blockquote>
+Two different strategies exist for declaring locations where external annotations should be search:
+<ul>
+<li>Per build path entry: each build path entry has an attribute "External annotations:" that can be
+set to the path where annotations regarding this particular build path entry should be searched.</li>
+<li>The compiler <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#external_annotations_from_all_locations">can be instructed</a> to search all
+build path locations for external annotations affecting any class files encountered during compilation.
+</ul>
<h3>Java Runtime Environments</h3>
<p>
External annotations can be directly attached to each JRE configured in the current workspace.
