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
Give every configuration flag its type, default, and failure mode
An entry named a flag and described what it does, and left the reader to
infer the rest. Whether a flag took a boolean, a list, or one name was
guessable from the surrounding prose at best; the default was stated for
nine of the thirty-nine and omitted for the rest, including every flag
whose default is a built-in list. A configuration that NullAway refuses
outright was described, where it was described at all, as a requirement
rather than as the message the build stops with.
State the type and the default above each entry's prose, read out of
`ErrorProneCLIFlagsConfig`: the built-in initializer annotations, the
fifteen excluded field annotations, the twenty-two known initializers,
the error URL, the serialization format version, and `false` for each of
the twenty booleans. Where the header now carries the default, drop the
sentence that repeated it.
Quote the five configurations that fail as NullAway loads, in the entry
for each flag involved: `AnnotatedPackages` with or without
`OnlyNullMarked`, `AcknowledgeAndroidRecent` without
`AcknowledgeRestrictiveAnnotations`, `JSpecifyJDKModels` outside JSpecify
mode, a multi-line `AutoFixSuppressionComment`, and `SerializeFixMetadata`
without a config path or alongside `SuggestSuppressions`.
State each interaction in both entries rather than one. `JSpecifyMode`
now names the four options that apply only in that mode;
`AcknowledgeRestrictiveAnnotations` names the Android option built on it;
`CastToNonNullMethod` records that `SuggestSuppressions` inserts a cast
in place of a suppression where `ErrorBuilder` can, and that the check it
turns on has an entry on the error page.
Fix two claims a reader could act on: the Android entry spelled the
namespace `-XepOpt:Nullaway:`, which Error Prone does not accept, and the
custom-initializer entry named two JUnit annotations where the built-in
list holds seven. Drop `currently` from the four sentences that dated
themselves.
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
Updated Configuration (markdown)
Updated Configuration (markdown)
Updated Configuration (markdown)
add docs for several config options
Updated Configuration (markdown)
Updated Configuration (markdown)
Updated Configuration (markdown)
Updated Configuration (markdown)
Document new JSpecify compatibility
Updated Configuration (markdown)
Document CustomGeneratedCodeAnnotations option
Updated Configuration (markdown)
Updated Configuration (markdown)
Document contract checking option
Updated Configuration (markdown)
Document the changes of PR #725
Updated Configuration (markdown)
Updated Configuration (markdown)
Updated Configuration (markdown)
Document -Xep:NullAway:CastToNonNullMethod
Fix link to AcknowledgeRestrictiveAnnotations
Document CustomNullableAnnotations and CustomNonnullAnnotations
Document AcknowledgeAndroidRecent