opendev/gerrit
Code Issues Proposed changes

Escape unescaped angle brackets in javadoc

Browse Source 
In ab11101fb2240a15cc6fdf1e31cdd675024edc7e {@code} tags got removed
from within a few javadoc <pre> tags, arguing that they are already in
a <pre> block. But <pre> on it's own does not allow unescaped use of
angle brackets, and hence javadoc building fails [1] again on Java 8.

Re-adding {@code} would be the canonical fix, as the {@code}
tag (quoting from the javadoc man page):

  Displays text in code font without interpreting the text as HTML
  markup or nested javadoc tags.

So it allows both using angle and curly brackets within {@code}.

However, as Eclipse currently chokes on braces within {@code} and
displays warnings [2], we escape the angle brackets for now to make
both eclipse and javadoc happy.

[1]

  [...]/registration/DynamicItem.java:70: error: malformed HTML
   *   DynamicSet.itemOf(binder(), new TypeLiteral<Thing<Foo>>() {});
                                                  ^
See
  http://builds.quelltextlich.at/gerrit/nightly/master-java_8/2015-06-14/extension-api-javadoc.jar.build.stderr.txt
  http://builds.quelltextlich.at/gerrit/nightly/master-java_8/2015-06-14/index.html#extension-api-javadoc.jar

[2] See the corresponding Eclipse bugs:
  https://bugs.eclipse.org/bugs/show_bug.cgi?id=258706
  https://bugs.eclipse.org/bugs/show_bug.cgi?id=206345

Change-Id: I39b2cfd06cbc5bd5d6a46dd567ac1abf21f09ee8
This commit is contained in:
Christian Aistleitner 2015-06-14 20:53:12 +02:00
parent 450b7d5cde
commit bf220b9c18
3 changed files with 4 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
gerrit-extension-api/src/main/java/com/google/gerrit/extensions/registration/DynamicItem.java
View File

@ -67,7 +67,7 @@ public class DynamicItem<T> {
* <p>
* Items must be defined in a Guice module before they can be bound:
* <pre>
* DynamicSet.itemOf(binder(), new TypeLiteral<Thing<Foo>>() {});
* DynamicSet.itemOf(binder(), new TypeLiteral&lt;Thing&lt;Foo&gt;&gt;() {});
* </pre>
*
* @param binder a new binder created in the module.

4
gerrit-extension-api/src/main/java/com/google/gerrit/extensions/registration/DynamicMap.java
View File

@ -67,8 +67,8 @@ public abstract class DynamicMap<T> implements Iterable<DynamicMap.Entry<T>> {
* Maps must be defined in a Guice module before they can be bound:
*
* <pre>
* DynamicMap.mapOf(binder(), new TypeLiteral<Thing<Bar>>(){});
* bind(new TypeLiteral<Thing<Bar>>() {})
* DynamicMap.mapOf(binder(), new TypeLiteral&lt;Thing&lt;Bar&gt;&gt;(){});
* bind(new TypeLiteral&lt;Thing&lt;Bar&gt;&gt;() {})
* .annotatedWith(Exports.named(&quot;foo&quot;))
* .to(Impl.class);
* </pre>

2
gerrit-extension-api/src/main/java/com/google/gerrit/extensions/registration/DynamicSet.java
View File

@ -61,7 +61,7 @@ public class DynamicSet<T> implements Iterable<T> {
* <p>
* Sets must be defined in a Guice module before they can be bound:
* <pre>
* DynamicSet.setOf(binder(), new TypeLiteral<Thing<Foo>>() {});
* DynamicSet.setOf(binder(), new TypeLiteral&lt;Thing&lt;Foo&gt;&gt;() {});
* </pre>
*
* @param binder a new binder created in the module.