Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk #1570

archanaNogriya · 2018-03-28T21:01:14Z

Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk without making any patch changes.

Fixes : #1569

Explanation:
Build has been failing with these 20 files.
Basically these errors are related to 2 issues and the fixes is required to work is detailed here

code text in the generated HTML
Text within {@code ...} will be automatically HTML-escaped however is not which is why above most of the files failed during compile. {@code ...} is more concise: easier to read (and type).


The {@code} is equivalent to  except that it uses allows you to use angle brackets < and > instead of HTML-entities < and &gt.

For example, {@code List} is equivalent to  List<String>.

See also the documentation for {@code}.

https://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#%7B@code%7D
also
https://blogs.oracle.com/darcy/javadoc-tip:-code-and-literal

Invalid syntax which has not been supported by HTML5

example : align or summary in is not supported in HTML5,

another example.

also there were few error such as take not closed or parameter was not given.

These 20 files I have fixed and I have created a pull request.

After these fixes, My personal local build is successfully passed.
Signed-off-by: Archana Nogriya archana.nogriya@uk.ibm.com

archanaNogriya · 2018-03-28T21:02:15Z

@DanHeidinga @pshipton

archanaNogriya · 2018-03-28T21:37:24Z

@DanHeidinga ,
I have made copyright fix adding 2018, still it fails for these files
17:28:42 The following files were modified and have incorrect copyrights
[Pipeline] echo
17:28:42 jcl/src/java.base/share/classes/java/lang/invoke/ConstantCallSite.java
[Pipeline] echo
17:28:42 jcl/src/java.base/share/classes/java/lang/invoke/MethodType.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/ClassLoadingMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/CompilationMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/GarbageCollectorMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/LockInfo.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/MemoryMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/MemoryManagerMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/MemoryPoolMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/OperatingSystemMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/PlatformLoggingMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/RuntimeMXBean.java
[Pipeline] echo
17:28:42 jcl/src/java.management/share/classes/java/lang/management/ThreadInfo.java

not sure what else I should be doing.

keithc-ca · 2018-03-28T21:48:29Z

If there are already two dates in the copyright notice, you should only ensure the second is the current year, not add a third. For example, in ConstantCallSite.java we want

Copyright (c) 2011, 2018 IBM Corp. and others

not

Copyright (c) 2011, 2011, 2018 IBM Corp. and others

pshipton · 2018-03-29T12:28:29Z

jcl/src/java.base/share/classes/java/lang/Class.java

@@ -2820,7 +2820,7 @@ public boolean isAnnotationPresent(Class<? extends Annotation> annotation) {

 /**
 * Cast this Class to a subclass of the specified Class. 
- * 
+ * @param <U> the type to cast this class object to


There shouldn't be two different @param statements for the single parameter.

Agree I will fix that. thanks

pshipton · 2018-03-29T12:30:39Z

jcl/src/java.base/share/classes/java/lang/String.java

@@ -138,7 +138,7 @@ static void checkOffset(int offset, int length) {
 		 *			  an Object to compare
 		 * @param o2
 		 *			  an Object to compare
-		 * @return an int < 0 if object1 is less than object2, 0 if they are equal, and > 0 if object1 is greater
+		 * @return an int is negative 0 if object1 is less than object2, 0 if they are equal, and greater than 0 if object1 is greater


"is negative" should be "less than". From "and greater than" remove "and"

Thanks @pshipton , I thought I have replaced this with {@code} .. let me see why my changes not reflected.

@pshipton Looks like you are seeing bit old code changes. Let me see why it is not refreshed with latest.

pshipton · 2018-03-29T12:32:33Z

jcl/src/java.base/share/classes/java/lang/StringBuffer.java

- * @exception	IndexOutOfBoundsException when <code>length < 0, start < 0</code> or
- *				<code>start + length > chars.length</code>
+ * @exception	IndexOutOfBoundsException
+ *				If {@code length} is negative, {@code start} is negative or ({@code start} + {@code start}) is grater {@code chars.length}


{@code start} + {@code start} should be {@code start + length}

pshipton · 2018-03-29T12:33:08Z

jcl/src/java.base/share/classes/java/lang/StringBuffer.java

- * @exception	IndexOutOfBoundsException when <code>index < 0</code> or
- *				<code>index >= length()</code>
+ * @exception	IndexOutOfBoundsException
+ *              If {@code index} is negative or {@code index} is grater or equal length()


typo in grater - greater

Some how I missed this line.. actually this should be fixed with this line,
when {@code index < 0} or {@code index >= length()}

pshipton · 2018-03-29T12:33:51Z

jcl/src/java.base/share/classes/java/lang/StringBuffer.java

- * @exception	StringIndexOutOfBoundsException when <code>start < 0, start > end</code> or
- *				<code>end > length()</code>
+ * @exception	StringIndexOutOfBoundsException
+ *				If {@code start} is negative, {@code start} is grater {@code end} or {@code end} is grater length()


grater - greater than (two places)

Some how I missed this line.. actually this should be fixed with this line,
when {@code}

pshipton · 2018-03-29T12:34:44Z

jcl/src/java.base/share/classes/java/lang/StringBuffer.java

- * @exception	IndexOutOfBoundsException when <code>start < 0, end > length(),
- *				start > end, index < 0, end - start > buffer.length - index</code>
+ * @exception	IndexOutOfBoundsException
+ *              If {@code start} is negative, {@code end} is greater length(),


greater - greater than

DanHeidinga

Thanks for taking this on. Fixing OpenJ9's javadoc has been a perpetual nice to have.

DanHeidinga · 2018-03-29T12:36:00Z

jcl/src/java.base/share/classes/java/lang/invoke/MethodHandles.java

@@ -3705,7 +3705,7 @@ private static boolean counterPredicate(int endValue, int counter) {
 	}

 	/**
-	 * Produce a loop handle that iterates over a range of values produced by an Iterator<T>
+	 * Produce a loop handle that iterates over a range of values produced by an Iterator object


We want to keep the <T> generic. Changing it to Iterator object changes the meaning. Maybe wrap it in {@code Iterator<T> }

Hi Dan, yes I have done all those changes.. some how it is not seen or refresh those latest changes here .. wired .. I am checking on it. you will see latest one .. these are bit old changes then I made everything with {@code}

DanHeidinga · 2018-03-29T12:38:56Z

jcl/src/java.management/share/classes/java/lang/management/LockInfo.java

@@ -145,7 +146,7 @@ public static LockInfo from(CompositeData compositeData) {
 	 * The string will hold both the name of the lock object's class and it's
 	 * identity hash code expressed as an unsigned hexadecimal. i.e.<br>
 	 * <p>
-	 * {@link #getClassName()}&nbsp;+&nbsp;&commat;&nbsp;+&nbsp;Integer.toHexString({@link #getIdentityHashCode()})
+	 * {@link #getClassName()} &nbsp;+&nbsp;&nbsp;+&nbsp;Integer.toHexString({@link #getIdentityHashCode()})
 	 * </p>


The </p> was deleted above. Was that accidental or was this one missed?

In these cases build has been complaining about closing P tag unnecessary, while getting to understand why it should be a problem then found HTML5

A p element’s end tag may be omitted if the p element is immediately followed by an address, article, aside, blockquote, dir, div, dl, fieldset, footer, form, h1, h2, h3, h4, h5, h6, header, hr, menu, nav, ol, p, pre, section, table, or ul element, or if there is no more content in the parent element and the parent element is not an a element.

So, for example, the following is invalid:

<a href="http://example.com><p>

This paragraph is unclosed </a>
But this is valid:

<div class="news"><p>Something important happened!</div>

And if you see the places where I removed closing P, Build worked fine.

pshipton · 2018-03-29T12:44:26Z

Apparently the commit is out of date. Please update it and make a comment when its ready for review.

pshipton · 2018-03-29T12:47:04Z

Also, please improve the content of the commit comment. It should have some context, and mention the changes are to javadoc comments.

archanaNogriya · 2018-04-04T13:57:11Z

@pshipton @DanHeidinga , this commit is ready to review now, Code is uptodate now with all my changes.

archanaNogriya · 2018-04-04T13:59:10Z

@andrew-m-leonard

pshipton · 2018-04-09T13:46:28Z

jcl/src/java.base/share/classes/java/lang/StringBuffer.java

- * @exception	IndexOutOfBoundsException when <code>index < 0</code> or
- *				<code>index >= length()</code>
+ * @exception	IndexOutOfBoundsException
+ *              If {@code index<0} or {@code index >= length()}


Please add spaces for index < 0

pshipton · 2018-04-09T13:51:19Z

jcl/src/java.management/share/classes/java/lang/management/ClassLoadingMXBean.java

 * <li>Using a javax.management.MBeanServerConnection.</li>
 * <li>Obtaining a proxy MXBean from the static
 * ManagementFactory.newPlatformMXBeanProxy(MBeanServerConnection connection,
- * String mxbeanName, Class <T>mxbeanInterface) method, passing in
+ * String mxbeanName, {@code Class<T> mxbeanInterface())} method, passing in


Seems @code should be around the entire API and not just the single parameter

pshipton · 2018-04-09T13:55:16Z

jcl/src/java.management/share/classes/java/lang/management/LockInfo.java

@@ -145,7 +146,7 @@ public static LockInfo from(CompositeData compositeData) {
 	 * The string will hold both the name of the lock object's class and it's
 	 * identity hash code expressed as an unsigned hexadecimal. i.e.<br>
 	 * <p>
-	 * {@link #getClassName()}&nbsp;+&nbsp;&commat;&nbsp;+&nbsp;Integer.toHexString({@link #getIdentityHashCode()})
+	 * {@link #getClassName()} &nbsp;+&nbsp;&nbsp;+&nbsp;Integer.toHexString({@link #getIdentityHashCode()})


Was it intentional to remove the &comma?

@pshipton this is intentional (not very happy with this deletion however could not find better solution so far ), for some reason html5 was complaining about "&commat" as invaid character, even putting in @code{} did not worked. I did try to find other options or reason this being invalid but could not find and when I removed this bit build worked. It would be great if we can find better option to fix this. Having @ build fails,

"openj9-openjdk/build/linux-x86_64-normal-server-release/support/j9jcl_sources/java.management/share/classes/java/lang/management/LockInfo.java:144: error: invalid entity &commat; * {@link #getClassName()} + &commat; + Integer.toHexString({@link #getIdentityHashCode()})"

Have you tried @?

https://www.toptal.com/designers/htmlarrows/symbols/at-symbol/

No, have not, let me try this one replacing. thanks

@keithc-ca thanks it worked :)

pshipton · 2018-04-09T13:58:33Z

Since this is ready to review, please remove the WIP from the title.

archanaNogriya · 2018-04-16T11:13:15Z

@pshipton : I was on vacation for last week, Let me make those changes as you suggested. thanks

without making any patch changes. Issue : eclipse-openj9#1569 Signed-off-by: Archana Nogriya <archana.nogriya@uk.ibm.com>

archanaNogriya

@pshipton All new changes are compiled and build . and build is green.

@keithc-ca : Thank you for your pointer , it worked :) and build is passed .

archanaNogriya force-pushed the master branch from 99c9243 to 7f49248 Compare March 28, 2018 21:27

archanaNogriya force-pushed the master branch 2 times, most recently from c94e9f1 to c02e416 Compare March 29, 2018 09:12

archanaNogriya closed this Mar 29, 2018

archanaNogriya reopened this Mar 29, 2018

pshipton reviewed Mar 29, 2018

View reviewed changes

DanHeidinga reviewed Mar 29, 2018

View reviewed changes

pshipton added the comp:vm label Mar 29, 2018

archanaNogriya force-pushed the master branch from c02e416 to ad004cd Compare April 4, 2018 13:39

archanaNogriya changed the title ~~WIP: Fix the openJ9 code to work with JDK file make/CompileJavaModules.gmk~~ WIP: Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk Apr 5, 2018

pshipton reviewed Apr 9, 2018

View reviewed changes

archanaNogriya changed the title ~~WIP: Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk~~ Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk Apr 16, 2018

fix the openJ9 code to work with JDK file make/CompileJavaModules.gmk

351fa5c

without making any patch changes. Issue : eclipse-openj9#1569 Signed-off-by: Archana Nogriya <archana.nogriya@uk.ibm.com>

archanaNogriya force-pushed the master branch from ad004cd to 351fa5c Compare April 17, 2018 08:44

archanaNogriya commented Apr 17, 2018

View reviewed changes

pshipton approved these changes Apr 17, 2018

View reviewed changes

pshipton merged commit 7fdb078 into eclipse-openj9:master Apr 17, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk #1570

Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk #1570

archanaNogriya commented Mar 28, 2018 •

edited

Loading

archanaNogriya commented Mar 28, 2018

archanaNogriya commented Mar 28, 2018

keithc-ca commented Mar 28, 2018

pshipton Mar 29, 2018

archanaNogriya Mar 29, 2018

pshipton Mar 29, 2018

archanaNogriya Mar 29, 2018

archanaNogriya Mar 29, 2018

pshipton Mar 29, 2018

pshipton Mar 29, 2018

archanaNogriya Mar 29, 2018

pshipton Mar 29, 2018

archanaNogriya Mar 29, 2018

pshipton Mar 29, 2018

DanHeidinga left a comment

DanHeidinga Mar 29, 2018

archanaNogriya Mar 29, 2018

DanHeidinga Mar 29, 2018

archanaNogriya Apr 4, 2018 •

edited

Loading

pshipton commented Mar 29, 2018

pshipton commented Mar 29, 2018

archanaNogriya commented Apr 4, 2018

archanaNogriya commented Apr 4, 2018

pshipton Apr 9, 2018

pshipton Apr 9, 2018

pshipton Apr 9, 2018

archanaNogriya Apr 16, 2018 •

edited

Loading

keithc-ca Apr 16, 2018

archanaNogriya Apr 16, 2018

archanaNogriya Apr 17, 2018

pshipton commented Apr 9, 2018

archanaNogriya commented Apr 16, 2018

archanaNogriya left a comment •

edited

Loading

Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk #1570

Fix the java doc contents in openJ9 class files to work with JDK file make/CompileJavaModules.gmk #1570

Conversation

archanaNogriya commented Mar 28, 2018 • edited Loading

archanaNogriya commented Mar 28, 2018

archanaNogriya commented Mar 28, 2018

keithc-ca commented Mar 28, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DanHeidinga left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

archanaNogriya Apr 4, 2018 • edited Loading

Choose a reason for hiding this comment

pshipton commented Mar 29, 2018

pshipton commented Mar 29, 2018

archanaNogriya commented Apr 4, 2018

archanaNogriya commented Apr 4, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

archanaNogriya Apr 16, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pshipton commented Apr 9, 2018

archanaNogriya commented Apr 16, 2018

archanaNogriya left a comment • edited Loading

Choose a reason for hiding this comment

archanaNogriya commented Mar 28, 2018 •

edited

Loading

archanaNogriya Apr 4, 2018 •

edited

Loading

archanaNogriya Apr 16, 2018 •

edited

Loading

archanaNogriya left a comment •

edited

Loading