On 5/14/20 5:26 AM, Jim Laskey wrote:
Are you looking at the text by Andrew in the bug?
It would seem so. I found the prettyprint markup in the CSR
distracting, so I was looking at my own javadoc build, but used the
older diff. I've rebuilt using the diff in the CSR.
I have a few minor suggestions:
* I would expect a colon, rather than a period, when "...as follows"
precedes a bulleted list.
* The wording of the third bullet point is good, though
I find I preferred the numeral 0 to the word "zero".
* The passage at the end of the @apiNote:
"...ignore the last line if the last line contains no characters (ends
with a line terminator.)"
is potentially confusing in that a line terminator is a character in and
of itself. Perhaps it could be reworked a little - something like:
* "...ignore the last line if the last line contains only a line
terminator." ?
or
* "...ignore the last line if the last line is empty (contains only a
line terminator)."
or something along those lines.
Thanks,
-Brent
On May 13, 2020, at 7:21 PM, Brent Christian <brent.christ...@oracle.com> wrote:
Hi, Jim
I have a few comments on the new wording (hopefully my understanding is
correct):
! * <li><p>If the block ends with a LF{@code "\n"} or CR{@code "\r"}
character,
! * then this implies the block closes in column 0 of the next line, and thus
! * implies an indent of 0.</p></li>
I feel like the opening wording could be improved. I presume this applies to, for
instance, both the "\n" construct (\005C \006e) as well as LF character
(\u000A). Maybe something like:
"If the block ends with a line break (LF, "\n", CR, "\r"),..."
Is it worth an example (or description) of what a block ending with a line
break looks like? e.g.
this is the end of the block.
"""
Also, it seems worth calling out here (or maybe later) that an indent of 0
means no leading white space is removed. Or maybe rework the ending phrase a
bit:
"..., then this implies the block closes in column 0 of the next line. In this
case the indent is 0, and no leading incidental white space is removed.
Thanks,
-Brent
On 5/11/20 12:38 PM, Jim Laskey wrote:
Sponsoring for Andrew Leonard. Please review the following CSR. Hopefully this
clarifies user's misunderstanding when a line seems to disappear when the
string ends with a line terminator.
CSR: https://bugs.openjdk.java.net/browse/JDK-8236688
JBS: https://bugs.openjdk.java.net/browse/JDK-8230800
Thank you.
Cheers,
-- Jim
