8278433: Use snippets in jdk.incubator.foreign documentation

[FrauBoes]

This change replaces <pre>{@code ...}</pre> blocks with the new @snippet tag. The change was applied to the panama-foreign repo with [1], now we bring it to the mainline. API doc (and Specdiff - not very informative) for reference [2]. 

[1] https://bugs.openjdk.java.net/browse/JDK-8277945
[2] http://cr.openjdk.java.net/~jboes/webrevs/8278433

---

Progress

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

Issue

• JDK-8278433: Use snippets in jdk.incubator.foreign documentation

Reviewers

• Maurizio Cimadamore (@mcimadamore - Reviewer) ⚠️ Review applies to 0aaf866

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 6771

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

Using diff file

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

[bridgekeeper]

👋 Welcome back jboes! 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]

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

• core-libs

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]

Webrevs

• 01: Full - Incremental (31606262)
• 00: Full (0aaf866d)

[pavelrappo]

Are differences in indentation between "before" and "after" intentional?

[pavelrappo]

Unrelated: this codebase could enjoy the inline version of the @return tag too; see JDK-8075778.

[mcimadamore]

Looks good (already reviewed it on panama-dev)

[openjdk]

@FrauBoes 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:

8278433: Use snippets in jdk.incubator.foreign documentation

Reviewed-by: mcimadamore

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 26 new commits pushed to the master branch:

• 1ea766d: 8278419: JFR jcmd option contract "This value cannot be changed once JFR has been initialized" is not enforced
• 62a7f5d: 8254318: Remove .hgtags
• d170682: 8278466: "spurious markup" warnings in snippets when building docs-reference
• 8ef1a23: 8278311: Debian packaging doesn't work
• 3524355: 8277882: New subnode ideal optimization: converting "c0 - (x + c1)" into "(c0 - c1) - x"
• 83e6a4c: 8255409: Support the new C_GetInterfaceList, C_GetInterface, and C_SessionCancel APIs in PKCS#11 v3.0
• 3cec700: 8278463: [test] Serialization WritePrimitive test revised for readFully test fails
• 03bf55f: 8277980: ObjectMethods::bootstrap throws NPE when lookup is null
• 3893f4f: 8278330: dump stack trace if the jvmti test nsk/jvmti/GetThreadState/thrstat002 is failed with wrong thread state
• b3faecf: 8276116: C2: optimize long range checks in int counted loops
• ... and 16 more: https://git.openjdk.java.net/jdk/compare/e4852c6f0aa25e7d40c577d507aedc7916ee8d50...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.

[mcimadamore]

Are differences in indentation between "before" and "after" intentional?

I believe so.

Unrelated: this codebase could enjoy the inline version of the @return tag too; see JDK-8075778.

Nice suggestion, thanks!

[FrauBoes]

Are differences in indentation between "before" and "after" intentional?

Yes, there are a few places where I touched up the indentation.

[FrauBoes]

/integrate

[openjdk]

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

• 1ea766d: 8278419: JFR jcmd option contract "This value cannot be changed once JFR has been initialized" is not enforced
• 62a7f5d: 8254318: Remove .hgtags
• d170682: 8278466: "spurious markup" warnings in snippets when building docs-reference
• 8ef1a23: 8278311: Debian packaging doesn't work
• 3524355: 8277882: New subnode ideal optimization: converting "c0 - (x + c1)" into "(c0 - c1) - x"
• 83e6a4c: 8255409: Support the new C_GetInterfaceList, C_GetInterface, and C_SessionCancel APIs in PKCS#11 v3.0
• 3cec700: 8278463: [test] Serialization WritePrimitive test revised for readFully test fails
• 03bf55f: 8277980: ObjectMethods::bootstrap throws NPE when lookup is null
• 3893f4f: 8278330: dump stack trace if the jvmti test nsk/jvmti/GetThreadState/thrstat002 is failed with wrong thread state
• b3faecf: 8276116: C2: optimize long range checks in int counted loops
• ... and 16 more: https://git.openjdk.java.net/jdk/compare/e4852c6f0aa25e7d40c577d507aedc7916ee8d50...master

Your commit was automatically rebased without conflicts.

[openjdk]

@FrauBoes Pushed as commit 84baea7.

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