Don't introduce line break at beginning of `<code>`

[mernst]

Consider this file:

public class LineBreakCode {

  /**
   * File with list of checkouts.  Set it to /dev/null to suppress reading.
   * Defaults to <code>$HOME/.mvc-checkouts</code>.
   */
  public String checkouts = "~/.mvc-checkouts";
}

The Javadoc comment gets reformatted as:

   * File with list of checkouts. Set it to /dev/null to suppress reading. Defaults to <code>
   * $HOME/.mvc-checkouts</code>.

Note that a line break has been introduced between <code> and the subsequent character, where there was no whitespace before. I think this makes the Javadoc comment harder to read.

Furthermore, the space is not closed up when google-java-format runs again, even if there is an opportunity to do so. If I subsequently add a few words to the first line of the reformatted comment:

   * File with list of checkouts. You can set it to /dev/null to suppress reading. Defaults to <code>
   * $HOME/.mvc-checkouts</code>.

and re-run google-java-format, then the result is:

   * File with list of checkouts. You can set it to /dev/null to suppress reading. Defaults to
   * <code>
   * $HOME/.mvc-checkouts</code>.

which carefully preserves the undesired line break that google-java-format added.

I should note that all versions of this look the same in the generated HTML API documentation, so my concern is to avoid unnecessarily munging the source code.

I think the best solution would be for google-java-format to not introduce whitespace immediately after a formatting tag such as <code>.

I have attached files that reproduce the behavior described above. linebreakcode.zip

[mernst]

The same problem occurs with <pre> tags. The lines within <pre> aren't broken, but new breaks are added after <pre> and before </pre>.

This is more serious because it changes how the formatted HTML API documentation looks. See attached test cases. linebreakpre.zip

[cpovirk]

Thanks for the report.

Inserting a newline after <pre> and before </pre>, despite how it changes the output, was intentional. We should probably document somewhere that we do change the output in this case. (I wonder if there are others?)

Doing the same for <code> was probably an oversight. I'm not sure offhand how hard this would be to fix. Hmm.

[cushon]

the space is not closed up when google-java-format runs again, even if there is an opportunity to do so

This does seem to work for {@code ... }, handling <code> differently seems like an oversight.

Part of the rationale for breaking before and after <pre> is that it's a block element, and breaking makes it consistent with what you get in the rendered html.

[mernst]

It doesn't seem to be consistent now. In the ClassFileVersion test case I provided, google-java-format introduced a break before one occurrence of </pre> but not before the other.

This made the formatting of the two <pre> blocks in the code inconsistent with one another: one was followed by two blank lines in the HTML output, whereas the other was followed by only normal paragraph spacing (one blank line).

My personal preference is not to have the extra trailing newline in the <pre> block, because then in the rendered HTML some paragraphs are separated by more space than others. This looks bad and confuses readers who wonder the reason for the extra space and apparent emphasis. I would rather have consistent spacing in the output, even if some line's length is 6 characters longer to accommodate </pre>. Per Chris's comment, maybe that's not the view of the gjf maintainers, though.

[cpovirk]

Ah, I hadn't thought about the additional inconsistency. It looks like we are willing to break between <pre> and the following character (and between a character and the following </pre>), so whether we do so depends on the length of the resulting line.

We have some logic to pin <p> to the following character, and we could reuse it for <pre>. I think it might be harder to pin </pre> to the preceding character. I think I had some ideas about a similar situation, but I'm blanking on what it was... :\

But I guess it's also possible that we'd just fully commit to putting <pre> and </pre> on their own lines. I think we're happy with that for <pre>{@code, but I think our current handling of <pre> may be more of an accident.

Thanks for raising all this. It does sound like we have some different preferences, but I think there's room for changes that will make things incrementally better (or at least more consistent).

[pugnascotia]

Another problem with breaking after <code> is where the wrapped text starts with an at-sign (@). This can actually breaks a build because the text is now treated as an annotation, which doesn't exist.