check-java-fences.py

Parses every java code fence in the docs pages with the JDK's own parser and reports the ones that are not valid Java. It parses only: no symbols are resolved and nothing is compiled against jars.

When to use

  • To find broken Java samples (missing class, stray markup, unbalanced braces) before readers do.
  • Run it by hand after editing a page. build-docs.py runs it with --strict in its Links stage (the Java fences row), so a fence that does not parse fails the build.
  • For anchors inside fences, use check-code-fences.py instead.

Usage

python3 scripts/check-java-fences.py
python3 scripts/check-java-fences.py --strict
python3 scripts/check-java-fences.py --java /path/to/jdk/bin/java

Options

OptionArgumentDefaultMeaning
--docs-rootdirectoryparent of the scripts/ folderThe docs checkout whose pages/ tree (plus the *.mdx pages in src/pages/about/) is scanned.
--javafile~/jdk/default/bin/javaThe java launcher to run JavaFenceParse.java with (JDK 17 or later).
--strictnoneoffExit 1 when any fence fails to parse. Without it the exit code is 0 whatever was found.

What it does

  1. Extracts every fence whose language is java (code_fences.iter_fences), skipping those whose meta contains the word fragment (write ```java fragment).
  2. Writes the fences to a temporary directory and runs java scripts/JavaFenceParse.java <dir> <count> once for all of them.
  3. The helper uses JavacTask.parse() and tries each fence as a compilation unit, then wrapped in a class body, then wrapped in a method body. If all three fail it splits the fence into independent pieces with JShell's completeness analysis (so a class declaration followed by loose statements is accepted) and parses every piece the same three ways. JShell is used only to split; it alone would accept incomplete constructs such as class Pet { ... }. A fence is reported only if every strategy fails.
  4. Prints file:line: java fence does not parse for each failure, then the totals.

Output and exit codes

Stdout only. Nothing is written outside the temporary directory.

CodeMeaning
0The scan completed (and, with --strict, nothing failed).
1--strict was given and at least one fence failed.

A missing JDK or a helper crash raises an error with the helper's stderr.

Gotchas

  • Placeholders such as ... or {...}, bare expressions, and signature-only snippets do not parse. Mark deliberate fragments with ```java fragment.
  • Because build-docs.py runs it with --strict, an unmarked fence that does not parse fails the build.
  • The helper needs the jdk.jshell module, which every full JDK 17+ ships.
  • Parse-only means a sample with an unknown type or a wrong method name still passes.
  • The line number is that of the opening fence.

See also

  • check-code-fences.py, code_fences.py, JavaFenceParse.java