Not all options/flags are documented in the wiki

[tbroyer]

While creating the net.ltgt.nullaway Gradle plugin, I compared https://github.com/uber/NullAway/blob/v0.6.6/nullaway/src/main/java/com/uber/nullaway/ErrorProneCLIFlagsConfig.java and https://github.com/uber/NullAway/wiki/Configuration and noticed there are a few options that are not documented in the wiki:

• SuggestSuppressions; this one is actually documented in https://github.com/uber/NullAway/wiki/Suppressing-Warnings
• AssertsEnabled
• ExhaustiveOverride
• CastToNonNullMethod
• AutoFixSuppressionComment (note: due to how options are passed to JavaC plugins and how JavaC parses them, you cannot put spaces in the value; this severely limits the usefulness of this option; this doesn't apply to Bazel though)

Btw, on master, since version 0.6.6, two options have been added:

• CheckOptionalEmptiness
• CheckOptionalEmptinessCustomClasses

the former being already documented in the wiki (but ignored by the current version, without any error or warning, mostly due to how flags work in Error Prone)

[issue filed as suggested on Twitter]

Fwiw you may want to migrate the documentation from the wiki to a markdown file in the repo, that way it can be kept in sync with the code, and looking at the file for the last version's tag would document that version. The downside is that you cannot fix/improve the documentation after the version has been tagged, but documentation can be part of the same PR that adds the option so is part of the code review. Just a suggestion. YMMV.

[lazaroclapp]

Hey @tbroyer, thanks for filing this issue!

I definitely like the approach of making docs part of the PR / release tagged commit / etc. We aren't doing it for 0.7.0, since I am right now cutting that release, but it's definitely worth doing in the future. Will leave this Issue open to figure that out.

Meanwhile, let me go ahead and update the Wiki :)

[lazaroclapp]

All options above are now documented either in the Configuration or Suppressing Warnings sections, as appropriate.

[tbroyer]

Fwiw, the problem with AutoFixSuppressionComment is not only Gradle, but also Maven (unless you're still using the plexus-compiler-javac-errorprone, which doesn't work with JDK10+ and has some classloading issues), Ant, or command-line JavaC; anywhere you're using Error Prone through -Xplugin:ErrorProne, as described in https://errorprone.info/docs/installation, rather than deeper integration into the build system through the (now deprecated BTW) com.google.errorprone.ErrorProneCompiler (like in Buck or Pants afaict, or plexus-compiler-javac-errorprone) or equivalent (like in Bazel).

[tbroyer]

AFAICT, AcknowledgeAndroidRecent has not been added to the wiki.

[msridhar]

AFAICT, AcknowledgeAndroidRecent has not been added to the wiki.

Thanks for catching this @tbroyer. I added some documentation here:

https://github.com/uber/NullAway/wiki/Configuration#acknowledge-android-recent-nullability-annotations

[dbwiddis]

Revisiting this after a few years. Good news: all 5 flags from the original report are now documented (AssertsEnabled, ExhaustiveOverride, CastToNonNullMethod, AutoFixSuppressionComment, and AcknowledgeAndroidRecent from the follow-up).

Diffing the current ErrorProneCLIFlagsConfig.java against the wiki turned up a newer, narrower gap — 8 flags added since without wiki docs:

• ErrorURL (since Add ErrorURL option #220)
• JarInferEnabled
• HandleWildcardGenerics (Enable HandleWildcardGenerics flag when building NullAway #1586)
• JSpecifyExperimental (Add JSpecifyExperimental configuration flag #1648)
• JSpecifyJDKModels (Enable JSpecify JDK models (under a flag) #1641)
• SerializeFixMetadata / SerializeFixMetadataVersion / FixSerializationConfigPath

Also found the reverse: LegacyAnnotationLocations is still documented in the wiki but was removed from source in #1640 — and a small typo (Nullaway: vs NullAway:) in the existing AcknowledgeAndroidRecent entry.

Before I draft wiki content: are the three SerializeFix* flags (feeding the separate nullaway-annotator tool) meant to stay undocumented here, or should they get a brief mention too? Happy to open a PR against msridhar/NullAway-wiki once scope is confirmed.

[msridhar]

Thanks for digging in here @dbwiddis!

• ErrorURL (since Add ErrorURL option #220)

This should definitely be documented.

• JarInferEnabled

We should document this one as well.

• HandleWildcardGenerics (Enable HandleWildcardGenerics flag when building NullAway #1586)
• JSpecifyExperimental (Add JSpecifyExperimental configuration flag #1648)
• JSpecifyJDKModels (Enable JSpecify JDK models (under a flag) #1641)

I was planning to discuss these in the next release notes. Maybe it'll be easier to document them after we cut the release?

Also found the reverse: LegacyAnnotationLocations is still documented in the wiki but was removed from source in #1640 — and a small typo (Nullaway: vs NullAway:) in the existing AcknowledgeAndroidRecent entry.

Yeah, I was going to document removal of this flag in the next release notes. Maybe we can document as "removed in NullAway 0.14.0"?

Before I draft wiki content: are the three SerializeFix* flags (feeding the separate nullaway-annotator tool) meant to stay undocumented here, or should they get a brief mention too? Happy to open a PR against msridhar/NullAway-wiki once scope is confirmed.

I think we can leave the SerializeFix* flags as undocumented; regular users shouldn't need to set them.

Thanks again!