Hi Pavel,
On 4/7/2020 1:07 PM, Pavel Rappo wrote:
Thanks, Joe. I presume you mean me changing this
* <code>@</code>{@code interface}
to this
* {@code @interface}
Correct.
Right? If so, then it renders the same way, and the `@interface` does not
confuse the Standard Doclet. After JDK-8241780 "Allow \n@ inside inline tags"
has been done and dusted we'll never have to think about that ever again.
I didn't double-check the history, but I may have added
<code>@</code>{@code interface}
way back when and if note in this particular instance I recall that kind
of javadoc contortion was necessary at the time to get (almost) the
desired effect.
Thanks,
-Joe
On 7 Apr 2020, at 20:23, Joe Darcy <joe.da...@oracle.com> wrote:
Hi Pavel,
Looks fine in general, assuming the change to Class.java renders correctly in
output.
Thanks,
-Joe
On 4/7/2020 8:28 AM, Pavel Rappo wrote:
Hi Ivan,
On 7 Apr 2020, at 09:11, Ivan Gerasimov <ivan.gerasi...@oracle.com> wrote:
Hi Pavel!
A couple of comments.
1)
java/util/logging/Formatter.java
This has one extra open curly brace:
"{{@literal <digit>}"
The leftmost curly brace is not a part of the "literal" inline tag, but rather
a part of the message format string. Have a look at the method that the comment
belongs to. Note what that method is looking for in a message string.
2)
grep finds some more typos of the same kind that you've spotted.
a) rgrep '^[ ]*\*'|grep ' ,'|less
This find number of potential typos. For example, the javadoc for VarHandle
[1] has 53 occurrances of space-before-comma. A few more are found in
j.l.Thread, j.io.DataOutput, j.l.String, etc.
b) rgrep '^[ ]*\*'|grep '\w- '|less
This find the word 'network' broken with a hyphen at [2] and also in
share/classes/sun/net/util/IPAddressUtil.java
(I only searched under src/java.base)
Thanks. I've included some of those: true positive, non-controversial,
and significant cases where I believe I sufficiently understood context.
For instance, I was not sure if I reliably grasped the applicability of the
"statically represented using varargs" phrase used widely across the VarHandle
type. It looks like that phrase was blankedly added to @return and @return tags.
So, I left it out for now.
The updated patch can be found here:
http://cr.openjdk.java.net/~prappo/8242230/webrev.01/
***
Some of the cases this patch addresses suggest that we might need to do
something about how the Standard Doclet treats newline characters in source
files. More often than not, newline characters are purely to control the width
of the source lines. When carried over to the output, they may produce
undesirable effects. Punctuation marks and contents of the Standard Doclet tags
may be affected.
That problem [1] is neither new nor trivial to address. Still, we should add
something to the Standard Doclet Specification [2].
I'm not sure what we can do about it now other than work around the current
behavior where it is significant.
-Pavel
P.S. CC'ing to javadoc-...@openjdk.java.net
-------------------------------------------------------------------------------
[1] https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap
[2]
https://docs.oracle.com/en/java/javase/14/docs/specs/javadoc/doc-comment-spec.html
With kind regards,
Ivan
[1]
https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/lang/invoke/VarHandle.html
[2]
https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/net/Inet4Address.html
On 4/6/20 11:28 AM, Pavel Rappo wrote:
Hello,
Please review the change for https://bugs.openjdk.java.net/browse/JDK-8242230:
http://cr.openjdk.java.net/~prappo/8242230/webrev.00/
This is a documentation cleanup. There are no code changes involved,
and the changes in documentation are mostly trivial.
The following packages are affected:
java.lang,
java.text,
java.util,
java.util.logging,
javax.lang.model.util,
jdk.internal.reflect
-Pavel
--
With kind regards,
Ivan Gerasimov
