RFR - JDK-8223775 String::stripIndent (Preview)

[Alex Buckley]

On 5/21/2019 4:19 PM, Alex Buckley wrote:
> On 5/21/2019 2:10 PM, Jim Laskey wrote:
>> Updated version http://cr.openjdk.java.net/~jlaskey/8223775/webrev-02
>
> API spec looks good, but it was a surprise to learn that stripIndent
> performs normalization of line terminators:
>
> "@return string with margins removed and line terminators normalized"
>
> The processing steps in the JEP (and the JLS) are clear that
> normalization happens before incidental white space removal. I realize
> that stripIndent performs separation and joining in such a way as to
> produce a string that looks like it was normalized prior to stripIndent,
> so the @return isn't wrong, but it's still confusing to make a big deal
> of normalization-first only for stripIndent to suggest normalization-last.

Stepping back, normalization is a nice thing for the multi-line-aware 
methods to do, but it's fundamentally just a "finishing touch". By 
mentioning it in the class-level spec as a general policy, we can dial 
back its appearance in stripIndent and indent.

The rest of this mail will appear disjointed, but put it all together in 
the javadoc (and imagine the class-level spec explains the goals of 
normalization) and it'll look nice. There are some tone changes below to 
make the method descriptions stop talking about what's "returned" and 
instead flow into the @return.


For stripIndent, bearing in mind that "margins" is no longer in the 
method summary:

@return a string with no incidental white space and with line 
terminators normalized

Description:

First, the individual lines of this string are extracted as if by using 
lines().  [If we're going to lean on lines(), then take its concept of 
extraction, rather than "conceptually separating" things. In the JLS I 
would say "as if by the execution of lines()" but the informal "using" 
phrase is fine for popular javadoc.]
...
Finally, the lines are joined into a new string, using the LF character 
(U+000A) to separate lines.  [The last clause is carefully chosen. We 
don't want to speak of a "line separator" because we already have "line 
terminator". We don't want to say "using the LF character to terminate 
lines" because joining embodies separation, not termination; see the 
@param of `join`.]


For indent, greater readability and consistency:

-----
public String indent​(int n)

Adjusts the indentation of each line of this string based on the value of n.

The individual lines of this string are extracted as if by using 
lines(). Each line is adjusted as described below, then all the adjusted 
lines are joined into a new string, using the LF character (U+000A) to 
separate lines.

If n > 0 ...
If n < 0 ...
If n == 0 ...

Returns:
     a string with indentation adjusted and line terminators normalized
-----


Finally, looking at lines: "Returns a stream of lines extracted from 
this string, separated by line terminators." makes it sound like the 
stream includes a line terminator element after every line element. The 
separation happened during the extraction, not the streaming. Recommend: 
  "Returns a stream of lines extracted from this string, split at line 
terminators."

Alex