RFR: (CSR) JDK-8236688 Clarify String::stripIndent javadoc when string ends with line terminator

[Brent Christian]

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.christian at 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
>