blob: 7f6ada8c62842b6aa412479bd61825b087411e7b [file] [view]
# 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
```bash
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
| Option | Argument | Default | Meaning |
|---|---|---|---|
| `--docs-root` | directory | parent of the `scripts/` folder | The docs checkout whose `pages/` tree (plus the `*.mdx` pages in `src/pages/about/`) is scanned. |
| `--java` | file | `~/jdk/default/bin/java` | The `java` launcher to run `JavaFenceParse.java` with (JDK 17 or later). |
| `--strict` | none | off | Exit 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.
| Code | Meaning |
|---|---|
| 0 | The 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`