8277026: Remove blank lines remaining from snippet markup #6623

pavelrappo · 2021-11-30T19:47:35Z

This PR proposes to omit lines from the snippet source if those lines consist only of markup and perhaps whitespace. For example, if this PR is integrated, these three snippets will result in the same output:

    // @start region="example1"
    if (v.isPresent()) {
        System.out.println("v: " + v.get());
    } // @end


    if (v.isPresent()) { // @start region="example2"
        System.out.println("v: " + v.get());
    } // @end


    // @start region="example3" :
    if (v.isPresent()) {
        System.out.println("v: " + v.get());
    // @end :
    }

While this change complicates the mental model for markup, it removes otherwise unavoidable inner blank lines in properties files, for example:

    coffee=espresso
    # @highlight:
    tea=ice

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8277026: Remove blank lines remaining from snippet markup

Reviewers

Jonathan Gibbons (@jonathan-gibbons - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/6623/head:pull/6623
$ git checkout pull/6623

Update a local copy of the PR:
$ git checkout pull/6623
$ git pull https://git.openjdk.java.net/jdk pull/6623/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 6623

View PR using the GUI difftool:
$ git pr show -t 6623

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/6623.diff

bridgekeeper · 2021-11-30T19:48:10Z

👋 Welcome back prappo! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2021-11-30T19:50:03Z

@pavelrappo The following label will be automatically applied to this pull request:

javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2021-11-30T19:55:17Z

Webrevs

00: Full (12e9bdbf)

jonathan-gibbons · 2021-11-30T20:59:55Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/snippet/Style.java

     * provided target.
     */
    record Link(String target) implements Style { }

    /**
     * A named style. Characters of this style are typically processed by
-     * wrapping into an HTML {@code SPAN} element with the {@code class}
+     * being wrapped into an HTML {@code SPAN} element with the {@code class}
     * attribute which is obtained from the provided name.
     */
    record Name(String name) implements Style { }

    /**
     * A marker of belonging to markup. Characters of this style are typically


The initial sentence is a little awkward. Can it be rephrased to be clearer?

What is the significance of the use of "typically", at the end of the line. Are there cases where characters with this style are not omitted from the output?

Are you referring to this?

A named style.

Feel free to take a stab at it; I'm not good with words.

jonathan-gibbons

Nice.

I guess I was more expecting to filter output lines, rather than mark up input lines, but so far, I can't think of a problem case where they might be different. I have a couple of comments/questions about comment text, but no issues with the code. I look forward to using this in practice.

openjdk · 2021-11-30T21:15:11Z

@pavelrappo This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8277026: Remove blank lines remaining from snippet markup

Reviewed-by: jjg

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 46 new commits pushed to the master branch:

e30e676: 8277606: String(String) constructor could copy hashIsZero
5a4a9bb: 8278019: ProblemList java/awt/dnd/BadSerializationTest/BadSerializationTest.java on linux and windows
15a6806: 8277434: tests fail with "assert(is_forwarded()) failed: only decode when actually forwarded"
21d9ca6: 8274983: C1 optimizes the invocation of private interface methods
98a9f03: 8277602: Deopt code does not extend the stack enough if the caller is an optimize entry blob
9150840: 8277899: Parallel: Simplify PSVirtualSpace::initialize logic
01cefc9: 8277977: Incorrect references to --enable-reproducible-builds in docs
69f56a0: 8264485: build.tools.depend.Depend.toString(byte[]) creates malformed hex strings
fecf906: 8267928: Loop predicate gets inexact loop limit before PhaseIdealLoop::rc_predicate
a5f2a58: 8277846: Implement fast-path for ASCII-compatible CharsetEncoders on ppc64
... and 36 more: https://git.openjdk.java.net/jdk/compare/987992042454f92936d3efbd01e7beb921e3b70e...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

pavelrappo · 2021-12-01T01:24:02Z

/integrate

openjdk · 2021-12-01T01:25:25Z

Going to push as commit da2be99.
Since your change was applied there have been 53 commits pushed to the master branch:

0a01baa: 8277986: Typo in javadoc of java.util.zip.ZipEntry#setTime
7049c13: 8231107: Allow store password to be null when saving a PKCS12 KeyStore
ab867f6: 8272162: S4U2Self ticket without forwardable flag
dd73e3c: 8277814: ConcurrentRefineThread should report rate when deactivating
65251f7: 8151594: Move concurrent refinement thread activation logging out of GC pause
f1c20e9: 8190748: java/text/Format/DateFormat/DateFormatTest.java and NonGregorianFormatTest fail intermittently
2942646: 8276683: Malformed Javadoc inline tags in JDK source in com/sun/tools/javac/util/RawDiagnosticFormatter.java
e30e676: 8277606: String(String) constructor could copy hashIsZero
5a4a9bb: 8278019: ProblemList java/awt/dnd/BadSerializationTest/BadSerializationTest.java on linux and windows
15a6806: 8277434: tests fail with "assert(is_forwarded()) failed: only decode when actually forwarded"
... and 43 more: https://git.openjdk.java.net/jdk/compare/987992042454f92936d3efbd01e7beb921e3b70e...master

Your commit was automatically rebased without conflicts.

openjdk · 2021-12-01T01:25:42Z

@pavelrappo Pushed as commit da2be99.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

pavelrappo added 2 commits Nov 26, 2021

Initial commit for 8277026

e76b9f0

Better test and clean up

12e9bdb

openjdk bot added the rfr label Nov 30, 2021

openjdk bot added the javadoc label Nov 30, 2021

jonathan-gibbons reviewed Nov 30, 2021

View changes

jonathan-gibbons approved these changes Nov 30, 2021

View changes

openjdk bot added the ready label Nov 30, 2021

openjdk bot closed this Dec 1, 2021

openjdk bot added integrated and removed ready rfr labels Dec 1, 2021

8277026: Remove blank lines remaining from snippet markup #6623

8277026: Remove blank lines remaining from snippet markup #6623

pavelrappo commented Nov 30, 2021 •

edited by openjdk[bot] bot

bridgekeeper bot commented Nov 30, 2021

openjdk bot commented Nov 30, 2021

mlbridge bot commented Nov 30, 2021

jonathan-gibbons Nov 30, 2021 •

edited

pavelrappo Nov 30, 2021 •

edited

jonathan-gibbons left a comment

openjdk bot commented Nov 30, 2021

pavelrappo commented Dec 1, 2021

openjdk bot commented Dec 1, 2021

openjdk bot commented Dec 1, 2021

8277026: Remove blank lines remaining from snippet markup #6623

8277026: Remove blank lines remaining from snippet markup #6623

Conversation

pavelrappo commented Nov 30, 2021 • edited by openjdk[bot] bot

Progress

Issue

Reviewers

Reviewing

bridgekeeper bot commented Nov 30, 2021

openjdk bot commented Nov 30, 2021

mlbridge bot commented Nov 30, 2021

Webrevs

jonathan-gibbons Nov 30, 2021 • edited

Choose a reason for hiding this comment

pavelrappo Nov 30, 2021 • edited

Choose a reason for hiding this comment

jonathan-gibbons left a comment

openjdk bot commented Nov 30, 2021

pavelrappo commented Dec 1, 2021

openjdk bot commented Dec 1, 2021

openjdk bot commented Dec 1, 2021

pavelrappo commented Nov 30, 2021 •

edited by openjdk[bot] bot

jonathan-gibbons Nov 30, 2021 •

edited

pavelrappo Nov 30, 2021 •

edited