Correct claims five reviews found in the recent wiki pages
Five reviews compared every page against the code. Thirteen of their
findings were claims a reader could act on and get wrong.
Four are about what an option does. `AcknowledgeRestrictiveAnnotations`
was documented as defaulting to `false`, but `acknowledgeRestrictive
Annotations()` returns `isAcknowledgeRestrictive || jspecifyMode`, so it
is on for every reader in JSpecify mode. `ExcludedClasses` and
`UnannotatedClasses` were called lists of class names, where
`isExcludedClass` and `isUnannotatedClass` both match with
`String.startsWith`, so they are prefixes. `SuggestSuppressions` was said
to insert `@SuppressWarnings("NullAway")`, where `ErrorBuilder` inserts
`@SuppressWarnings("NullAway.Init")` for a field-initialization error.
`KnownInitializers` was said to default to 22 Android methods plus
others, where 22 is the whole set: 20 Android, one annotation-processing
method, and one Flink method.
Three are about when a diagnostic appears. The wildcard-annotation error
needs `HandleWildcardGenerics` as well as JSpecify mode, which
`NullAway.matchAnnotatedType` requires and the entry did not mention. The
`castToNonNull` error also fires for methods a library model registers,
which is why the message carries an argument position, and it is
suppressed inside constructors and initializers. The conditional-
expression error compares each branch against the type the context
requires, not the branches against each other, so the entry forbade
`@Nullable Integer[] t = c ? new Integer[0] : new @Nullable Integer[0]`,
which `JSpecifyArrayTests` expects to compile.
Two are version claims. Compatibility said 0.13.0 raised the Error Prone
floor from 2.10.0; 0.11.0 had already raised it to 2.14.0, and both later
bumps landed inside 0.13.0. It also cited NullAway's own test suite as
evidence, which no reader of that page can act on, in place of Error
Prone's release notes.
The rest are scope: `@NullUnmarked` has no `MODULE` target, so a module
can only be `@NullMarked`; `JSpecifyExperimental` turns on three
features, not the two Adopting NullAway listed; and Error-Messages
presented the built-in initializer annotations as two where the record
lists seven.
Also drop the rationale the reviews could not source, in particular the
claim that reporting only top-level classes follows from nested classes
being covered, and the claim that the local-variable option is on so that
the check reports every location the specification lists, which the
check's own documented limits deny. Give Compatibility the table its five
sections of recurring version numbers were asking for, cut the second
full copy of the patch-mode version gap so the record has one home, and
add the `NullAway.Optional` suppression to the page that lists the
others.
Assisted-by: Claude Code (claude-opus-5)
vlsi
committed
Sep 5, 2026
Add compatibility and adoption pages, and index the configuration flags
Three questions had no page. Which JDK and Error Prone versions a
NullAway version needs was answered in three places at once, none of
them a reference: the README carried JDK 17 and Error Prone 2.36.0,
JSpecify Support the javac requirement for type-use annotations in
bytecode, and Suppressing Warnings the Error Prone range in which patch
mode does not work. How to switch an existing codebase on, and how to
move from AnnotatedPackages to OnlyNullMarked or into JSpecify mode, was
answered nowhere.
Add Compatibility, which states the requirements and the combinations
that fail, including that Error Prone 2.43.0 dropped JDK 17, so a build
still on JDK 17 stops at 2.42.0. Add Adopting NullAway, which orders the
steps and links the reference entry for each. Both link to the pages
that own the detail rather than restating it, and both are linked from
Home and the sidebar.
In Configuration, document the five flags the reference did not list.
SuggestSuppressions and AutoFixSuppressionComment appeared only on
Suppressing Warnings; SerializeFixMetadata, FixSerializationConfigPath
and SerializeFixMetadataVersion appeared nowhere, and now say that they
serialize for NullAwayAnnotator. Add an alphabetical index of all 41
flags above the entries, generated from the entries themselves, so that
a reader holding a flag name can reach its section without scrolling
past 33 headings.
Also correct two claims a reader could act on. Supported Annotations
listed the non-null simple names as `@NonNull`, `@NonNull` and
`@NotNull`; Nullness.isNonNullAnnotation accepts `@NonNull`, `@Nonnull`
and `@NotNull`. Suppressing Warnings spelled the suppression-comment
flag `--Xep:NullAway:AutoFixSuppressionComment`, which is neither the
right prefix nor the right namespace; it is
`-XepOpt:NullAway:AutoFixSuppressionComment`. Give the remaining
untagged code fences their language.
Assisted-by: Claude Code (claude-opus-5)
vlsi
committed
Sep 5, 2026
Document the twelve missing error messages, and add wiki navigation
`ErrorMessage.MessageTypes` declares 29 kinds of diagnostic, of which
Error-Messages.md explained sixteen. A reader who searched for the text
of a JSpecify-mode error found nothing: none of the generics errors had
an entry, and neither did the array write, the `switch` selector, the
`Optional.get()` check, the `castToNonNull` check, or the annotation on
an enclosing type.
Add an entry for each, in the shape the page already uses, quoting the
emitted text and building the example from the test that covers it. The
five generic pseudo-assignment errors share one entry, since they share
one message; the four override forms share another. Fix the one table
of contents link that lost its `#` and so pointed at a file.
Add `_Sidebar.md`, which GitHub renders beside every page. Readers
arrive at a heading from a search engine, and until now a page carried
no way to reach the rest of the wiki.
Rewrite Home.md, which listed the nine pages in no particular order and
never mentioned the README, the only place installation is documented.
Group the pages by what the reader is doing, and say what each one
answers.
Assisted-by: Claude Code (claude-opus-5)
vlsi
committed
Sep 5, 2026
docs: document deliberate unsoundness (#3)
* docs: document deliberate unsoundness
* edits
---------
Co-authored-by: Manu Sridharan <msridhar@gmail.com>