RFR: [15] JDK-8236048: Cleanup use of Utils.normalizeNewlines

[Pavel Rappo]

Jon,

Could you please explain why "generated files should only contain \n"?

Is it possible to perform the `rawHtml.indexOf('\r') == -1` optimization check first thing in
normalizeNewlines?

New mechanics of string normalization is more readable, albeit is probably slower in a typical case.
Old mechanics used bulk append, whereas the new one goes char by char. Not sure if it is of any
practical significance though.

I wonder if normalization should be deferred until the latest possible moment. The reason is that
this operation doesn't seem to be additive, i.e.

    normalizeNewlines(A) + normalizeNewlines(B) != normalizeNewlines(A + B).

-Pavel

> On 17 Dec 2019, at 02:30, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> Please review a moderately simple change for javadoc, to improve the way that newlines in user input (doc comments and values for command-line options) are handled, reducing the amount of overall string copying.  The underlying issue is that user newlines may be \n, \r or \r\n, but the generated files should only contain \n.
> 
> Instead of using Utils.normalizeNewlines (which does an unconditional copy) at a number of sites, the normalization is now done in StringContent and RawHtml. In the case of StringContent, the normalization is done while checking and handling the escape sequences for < > &; in the case of RawHtml, it is done when constructing the object, but only if the argument contains \r.
> 
> There are no good pre-existing tests for testing newline behavior, and so a new test is provided that runs javadoc on input containing the different kinds of newline.  The test revealed a previously unknown bug, that non-standard newslines in command-line option values were not handled correctly.
> 
> The output is also the same (before-and-after) for the generated JDK API docs.
> 
> -- Jon
> 
> JBS: https://bugs.openjdk.java.net/browse/JDK-8236048
> Webrev: http://cr.openjdk.java.net/~jjg/8236048/webrev.00/index.html
>