JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

joe darcy
Hello,

Even after the fixes for JDK-8172458, there is still a lingering HTML5
compliance issue in javax.lang.model.* in addition to a few javadoc
linkage problems. These should all be fixed; small patch below.

With the patch, the code is doclint clean under both HTML 4.01 and HTML
5 output.

(I thought the linkage problem would have been caught by the javac and
javadoc build options, but apparently not.)

Thanks,

-Joe

diff -r 50c877258ca9
src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
---
a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
Fri Jan 20 18:24:50 2017 -0800
+++
b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
Sun Jan 22 16:23:28 2017 -0800
@@ -35,7 +35,7 @@
   * type is a kind of class and an annotation type is a kind of
   * interface.
   *
- * <p> <a name="ELEM_VS_TYPE"></a>
+ * <p> <a id="ELEM_VS_TYPE"></a>
   * While a {@code TypeElement} represents a class or interface
   * <i>element</i>, a {@link DeclaredType} represents a class
   * or interface <i>type</i>, the latter being a use
diff -r 50c877258ca9
src/java.compiler/share/classes/javax/lang/model/util/Elements.java
---
a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
Fri Jan 20 18:24:50 2017 -0800
+++
b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java
Sun Jan 22 16:23:28 2017 -0800
@@ -29,6 +29,7 @@
  import java.util.List;
  import java.util.Map;

+import javax.annotation.processing.ProcessingEnvironment;
  import javax.lang.model.AnnotatedConstruct;
  import javax.lang.model.element.*;

@@ -91,7 +92,7 @@
       * If the named module cannot be found, null is returned. One
situation where a module
       * cannot be found is if the environment does not include modules,
such as
       * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source
version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source
version} without modules.
       *
       * @param name  the name
       * @return the named module element, or {@code null} if it cannot
be found
@@ -331,7 +332,7 @@
       * If there is no module for the element, null is returned. One
situation where there is
       * no module for an element is if the environment does not include
modules, such as
       * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source
version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source
version} without modules.
       *
       * @param type the element being examined
       * @return the module of an element

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

Martin Buchholz-3
It's good.

There's a persistent ecosystem nuisance that tools don't recognize imports done purely for javadoc's benefit and complain.  For this reason I generally use fully qualified @links in the javadoc, even though it's uglier.


On Sun, Jan 22, 2017 at 4:45 PM, joe darcy <[hidden email]> wrote:
Hello,

Even after the fixes for JDK-8172458, there is still a lingering HTML5 compliance issue in javax.lang.model.* in addition to a few javadoc linkage problems. These should all be fixed; small patch below.

With the patch, the code is doclint clean under both HTML 4.01 and HTML 5 output.

(I thought the linkage problem would have been caught by the javac and javadoc build options, but apparently not.)

Thanks,

-Joe

diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Sun Jan 22 16:23:28 2017 -0800
@@ -35,7 +35,7 @@
  * type is a kind of class and an annotation type is a kind of
  * interface.
  *
- * <p> <a name="ELEM_VS_TYPE"></a>
+ * <p> <a id="ELEM_VS_TYPE"></a>
  * While a {@code TypeElement} represents a class or interface
  * <i>element</i>, a {@link DeclaredType} represents a class
  * or interface <i>type</i>, the latter being a use
diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/util/Elements.java
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Sun Jan 22 16:23:28 2017 -0800
@@ -29,6 +29,7 @@
 import java.util.List;
 import java.util.Map;

+import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.AnnotatedConstruct;
 import javax.lang.model.element.*;

@@ -91,7 +92,7 @@
      * If the named module cannot be found, null is returned. One situation where a module
      * cannot be found is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param name  the name
      * @return the named module element, or {@code null} if it cannot be found
@@ -331,7 +332,7 @@
      * If there is no module for the element, null is returned. One situation where there is
      * no module for an element is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param type the element being examined
      * @return the module of an element


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

joe darcy

Hi Martin,

Thanks for the review.

For better tooling interaction, I'll switch to the fully qualified name for the links.

Also, upon closer examination, there are not incoming links to the anchor so I'll just delete it.

Updated patch below.

Thanks,

-Joe

diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java    Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java    Mon Jan 23 10:19:24 2017 -0800
@@ -35,8 +35,7 @@
  * type is a kind of class and an annotation type is a kind of
  * interface.
  *
- * <p> <a name="ELEM_VS_TYPE"></a>
- * While a {@code TypeElement} represents a class or interface
+ * <p> While a {@code TypeElement} represents a class or interface
  * <i>element</i>, a {@link DeclaredType} represents a class
  * or interface <i>type</i>, the latter being a use
  * (or <i>invocation</i>) of the former.
diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/util/Elements.java
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java    Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java    Mon Jan 23 10:19:24 2017 -0800
@@ -91,7 +91,9 @@
      * If the named module cannot be found, null is returned. One situation where a module
      * cannot be found is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain
+     * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
+     * source version} without modules.
      *
      * @param name  the name
      * @return the named module element, or {@code null} if it cannot be found
@@ -331,7 +333,9 @@
      * If there is no module for the element, null is returned. One situation where there is
      * no module for an element is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain
+     * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
+     * source version} without modules.
      *
      * @param type the element being examined
      * @return the module of an element


On 1/23/2017 8:57 AM, Martin Buchholz wrote:
It's good.

There's a persistent ecosystem nuisance that tools don't recognize imports done purely for javadoc's benefit and complain.  For this reason I generally use fully qualified @links in the javadoc, even though it's uglier.


On Sun, Jan 22, 2017 at 4:45 PM, joe darcy <[hidden email]> wrote:
Hello,

Even after the fixes for JDK-8172458, there is still a lingering HTML5 compliance issue in javax.lang.model.* in addition to a few javadoc linkage problems. These should all be fixed; small patch below.

With the patch, the code is doclint clean under both HTML 4.01 and HTML 5 output.

(I thought the linkage problem would have been caught by the javac and javadoc build options, but apparently not.)

Thanks,

-Joe

diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Sun Jan 22 16:23:28 2017 -0800
@@ -35,7 +35,7 @@
  * type is a kind of class and an annotation type is a kind of
  * interface.
  *
- * <p> <a name="ELEM_VS_TYPE"></a>
+ * <p> <a id="ELEM_VS_TYPE"></a>
  * While a {@code TypeElement} represents a class or interface
  * <i>element</i>, a {@link DeclaredType} represents a class
  * or interface <i>type</i>, the latter being a use
diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/util/Elements.java
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Sun Jan 22 16:23:28 2017 -0800
@@ -29,6 +29,7 @@
 import java.util.List;
 import java.util.Map;

+import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.AnnotatedConstruct;
 import javax.lang.model.element.*;

@@ -91,7 +92,7 @@
      * If the named module cannot be found, null is returned. One situation where a module
      * cannot be found is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param name  the name
      * @return the named module element, or {@code null} if it cannot be found
@@ -331,7 +332,7 @@
      * If there is no module for the element, null is returned. One situation where there is
      * no module for an element is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param type the element being examined
      * @return the module of an element



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

Martin Buchholz-3
Looks good.

On Mon, Jan 23, 2017 at 10:22 AM, joe darcy <[hidden email]> wrote:

Hi Martin,

Thanks for the review.

For better tooling interaction, I'll switch to the fully qualified name for the links.

Also, upon closer examination, there are not incoming links to the anchor so I'll just delete it.

Updated patch below.

Thanks,

-Joe

diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java    Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java    Mon Jan 23 10:19:24 2017 -0800
@@ -35,8 +35,7 @@
  * type is a kind of class and an annotation type is a kind of
  * interface.
  *
- * <p> <a name="ELEM_VS_TYPE"></a>
- * While a {@code TypeElement} represents a class or interface
+ * <p> While a {@code TypeElement} represents a class or interface
  * <i>element</i>, a {@link DeclaredType} represents a class
  * or interface <i>type</i>, the latter being a use
  * (or <i>invocation</i>) of the former.
diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/util/Elements.java
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java    Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java    Mon Jan 23 10:19:24 2017 -0800
@@ -91,7 +91,9 @@
      * If the named module cannot be found, null is returned. One situation where a module
      * cannot be found is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain
+     * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
+     * source version} without modules.
      *
      * @param name  the name
      * @return the named module element, or {@code null} if it cannot be found
@@ -331,7 +333,9 @@
      * If there is no module for the element, null is returned. One situation where there is
      * no module for an element is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain
+     * javax.annotation.processing.ProcessingEnvironment#getSourceVersion
+     * source version} without modules.
      *
      * @param type the element being examined
      * @return the module of an element


On 1/23/2017 8:57 AM, Martin Buchholz wrote:
It's good.

There's a persistent ecosystem nuisance that tools don't recognize imports done purely for javadoc's benefit and complain.  For this reason I generally use fully qualified @links in the javadoc, even though it's uglier.


On Sun, Jan 22, 2017 at 4:45 PM, joe darcy <[hidden email]> wrote:
Hello,

Even after the fixes for JDK-8172458, there is still a lingering HTML5 compliance issue in javax.lang.model.* in addition to a few javadoc linkage problems. These should all be fixed; small patch below.

With the patch, the code is doclint clean under both HTML 4.01 and HTML 5 output.

(I thought the linkage problem would have been caught by the javac and javadoc build options, but apparently not.)

Thanks,

-Joe

diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Sun Jan 22 16:23:28 2017 -0800
@@ -35,7 +35,7 @@
  * type is a kind of class and an annotation type is a kind of
  * interface.
  *
- * <p> <a name="ELEM_VS_TYPE"></a>
+ * <p> <a id="ELEM_VS_TYPE"></a>
  * While a {@code TypeElement} represents a class or interface
  * <i>element</i>, a {@link DeclaredType} represents a class
  * or interface <i>type</i>, the latter being a use
diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/util/Elements.java
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Sun Jan 22 16:23:28 2017 -0800
@@ -29,6 +29,7 @@
 import java.util.List;
 import java.util.Map;

+import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.AnnotatedConstruct;
 import javax.lang.model.element.*;

@@ -91,7 +92,7 @@
      * If the named module cannot be found, null is returned. One situation where a module
      * cannot be found is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param name  the name
      * @return the named module element, or {@code null} if it cannot be found
@@ -331,7 +332,7 @@
      * If there is no module for the element, null is returned. One situation where there is
      * no module for an element is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param type the element being examined
      * @return the module of an element




Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

Jonathan Gibbons
In reply to this post by Martin Buchholz-3
Do you have any specific tools in mind?  Can we file RFEs against those tools?

-- Jon

On 01/23/2017 08:57 AM, Martin Buchholz wrote:
It's good.

There's a persistent ecosystem nuisance that tools don't recognize imports done purely for javadoc's benefit and complain.  For this reason I generally use fully qualified @links in the javadoc, even though it's uglier.


On Sun, Jan 22, 2017 at 4:45 PM, joe darcy <[hidden email]> wrote:
Hello,

Even after the fixes for JDK-8172458, there is still a lingering HTML5 compliance issue in javax.lang.model.* in addition to a few javadoc linkage problems. These should all be fixed; small patch below.

With the patch, the code is doclint clean under both HTML 4.01 and HTML 5 output.

(I thought the linkage problem would have been caught by the javac and javadoc build options, but apparently not.)

Thanks,

-Joe

diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java Sun Jan 22 16:23:28 2017 -0800
@@ -35,7 +35,7 @@
  * type is a kind of class and an annotation type is a kind of
  * interface.
  *
- * <p> <a name="ELEM_VS_TYPE"></a>
+ * <p> <a id="ELEM_VS_TYPE"></a>
  * While a {@code TypeElement} represents a class or interface
  * <i>element</i>, a {@link DeclaredType} represents a class
  * or interface <i>type</i>, the latter being a use
diff -r 50c877258ca9 src/java.compiler/share/classes/javax/lang/model/util/Elements.java
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Fri Jan 20 18:24:50 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java Sun Jan 22 16:23:28 2017 -0800
@@ -29,6 +29,7 @@
 import java.util.List;
 import java.util.Map;

+import javax.annotation.processing.ProcessingEnvironment;
 import javax.lang.model.AnnotatedConstruct;
 import javax.lang.model.element.*;

@@ -91,7 +92,7 @@
      * If the named module cannot be found, null is returned. One situation where a module
      * cannot be found is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param name  the name
      * @return the named module element, or {@code null} if it cannot be found
@@ -331,7 +332,7 @@
      * If there is no module for the element, null is returned. One situation where there is
      * no module for an element is if the environment does not include modules, such as
      * an annotation processing environment configured for
-     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.      *
+     * a {@linkplain ProcessingEnvironment#getSourceVersion source version} without modules.
      *
      * @param type the element being examined
      * @return the module of an element



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

Martin Buchholz-3


On Thu, Apr 20, 2017 at 1:38 PM, Jonathan Gibbons <[hidden email]> wrote:
Do you have any specific tools in mind?  Can we file RFEs against those tools?

IIRC, checkstyle  http://checkstyle.sourceforge.net/ has an unused import checker that doesn't recognize usage in doc comments.  I have the vague feeling there are others.  I have the feeling checkstyle's checks are not very good, but improving them would be a full time job.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: JDK 9 RFR of JDK-8173164: Resolve remaining HTML5 issues in javax.lang.model.*

Liam Miller-Cushon
Newer versions of checkstyle support it: http://checkstyle.sourceforge.net/config_imports.html#UnusedImports

I remember some disagreement between other tools about whether e.g. `{@link #foo(Bar)}` needs an import for `Bar`, but javadoc's handling of that seems to have improved in 9.

On Thu, Apr 20, 2017 at 1:51 PM, Martin Buchholz <[hidden email]> wrote:


On Thu, Apr 20, 2017 at 1:38 PM, Jonathan Gibbons <[hidden email]> wrote:
Do you have any specific tools in mind?  Can we file RFEs against those tools?

IIRC, checkstyle  http://checkstyle.sourceforge.net/ has an unused import checker that doesn't recognize usage in doc comments.  I have the vague feeling there are others.  I have the feeling checkstyle's checks are not very good, but improving them would be a full time job.

Loading...