Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
mernst opened this issue Oct 11, 2016 · 6 comments · May be fixed by #638
Open

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

mernst opened this issue Oct 11, 2016 · 6 comments · May be fixed by #638

Comments

@mernst
Copy link
Contributor

mernst commented Oct 11, 2016

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
Copy link
Contributor Author

mernst commented Oct 11, 2016

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
Copy link
Member

cpovirk commented Oct 11, 2016

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
Copy link
Collaborator

cushon commented Oct 11, 2016

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
Copy link
Contributor Author

mernst commented Oct 11, 2016

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
Copy link
Member

cpovirk commented Oct 15, 2016

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
Copy link

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.

now pushed a commit to now/google-java-format that referenced this issue Aug 1, 2021
If a CODE_OPEN_TAG token is followed by a LITERAL token, break before writing
the CODE_OPEN_TAG token if writing it will result in us eating up the remainder
of the current line.

Partially fixes google#84.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants