Followup; was Re: RFR [15] 8242230: Whitespace typos, relaxed javadoc, formatting

[Pavel Rappo]

Certainly, Jon.

Doc comments in source code and documentation produced from them look
differently. When writing doc comments, authors have some model in their heads
of how these comments will be processed by the documentation generator and what
the result might look like. If that model is inaccurate, there might be problems.

One of such problems is whitespace and indentation. Constructs that should be
contiguous become separated because authors might've had a wrong concept on how
the formatting they apply in source maps to that of the resulting documentation.

Typically, multiple consecutive whitespace characters are collapsed into a
single whitespace character and a newline character is translated into a single
horizontal whitespace. I'm not sure if that should be obvious or specified, but
I often see the results of not paying enough attention to this: a punctuation
mark that starts a new line, a compound hyphenated word having a newline
character after a hyphen, or a {@code} tag whose contents span multiple lines.

-Pavel

> On 7 Apr 2020, at 17:59, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> 
> 
> On 4/7/20 8:28 AM, Pavel Rappo wrote:
>> 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.
> 
> Pavel,
> 
> Can you explain more about your concerns in this area?
> 
> -- Jon
>