maven instruction incomplete

[delanym]

If you search version 3.21.1 of https://checkerframework.org/manual/ for "annotatedJdk" you'll only get one result, which is the use of this variable. There is no assignment.

[mernst]

Thanks for reporting this mistake, and our apologies for the confusion.
You can omit that line.

Lines like that were removed in 415220c .
However, e4369bb mistakenly reintroduced this one occurrence.

[delanym]

THanks for the update. I made a specific ticket about the documentation in the hope it would prompt a review of the documentation more generally. I'm still not able to get the annotation processor to work in Maven for jdk8. I appreciate the documentation is there to provide a reference for the available options, but I find it very hard to follow this as a how-to.

[mernst]

@delanym I'm sorry you are having trouble. I would like to help you, but unfortunately, from your description I cannot tell what is wrong nor reproduce your problem. I do know that many other people have followed the instructions successfully. Good luck!

[delanym]

I've since upgraded to JDK11, and after learning how to configure the Mapstruct annotation processor I thought I'd have another go at getting Checkerframework to work.

Here is my working profile

    <profile>
      <id>checkerframework</id>
      <activation>
        <property>
          <name>checkerframework</name>
        </property>
      </activation>
      <dependencyManagement>
        <dependencies>
          <dependency>
            <groupId>org.checkerframework</groupId>
            <artifactId>checker</artifactId>
            <version>${dep.checkerframework}</version>
          </dependency>
        </dependencies>
      </dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>org.checkerframework</groupId>
          <artifactId>checker</artifactId>
          <scope>provided</scope>
        </dependency>
      </dependencies>
      <build>
        <plugins>
          <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
              <annotationProcessorPaths combine.children="append">
                <path>
                  <groupId>org.checkerframework</groupId>
                  <artifactId>checker</artifactId>
                  <version>${dep.checkerframework}</version>
                </path>
              </annotationProcessorPaths>
              <annotationProcessors combine.children="append">
                <annotationProcessor>org.checkerframework.checker.nullness.NullnessChecker</annotationProcessor>
              </annotationProcessors>
              <compilerArgs combine.children="append">
                <arg>-Awarns</arg>
              </compilerArgs>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>

Hope you don't mind if I make some suggestions:
I don't think you need a checker-maven-plugin. The documentation just needs to be clearer. Less ifs and buts - leave the exceptional circumstances like support for JDK8 for its own section.

The checkers should be grouped under a single heading.

If you're set on a single page, you might want to use the same documentation system as https://junit.org/junit5/docs/current/user-guide/

The documentation https://checkerframework.org/manual/#maven mentions a bug in Maven compiler plugin, but this has been resolved.

[mernst]

Thanks very much for your feedback. We appreciate your suggestions!

I have opened two pull requests to address different parts of this issue:
#5118
#5119
If you have time to review those pull requests, we your feedback would be welcome.

I'm not sure what you mean by "The checkers should be grouped under a single heading." Could you clarify?

If you have other suggestions, please let us know, or open a pull request.
We do not use Maven, so we depend on Maven users in our community to help with that aspect of the documentation.

(One thing that would be helpful to us is opening a new issue for each distinct problem/suggestion/improvement, so that we can be sure not to overlook any of them.)

Thanks again.

[delanym]

@mernst ill be happy to contribute to the Maven section of documentation once I know more about the framework. At the moment I'm just here to 'exploit' whatever improvements it can offer to the codebase I work on. I want to try out all the builtin checkers (without adding annotations to my code), but Im having a hard time finding them all.

<annotationProcessors combine.children="append">
  <!-- <annotationProcessor>org.checkerframework.checker.interning.InterningChecker</annotationProcessor> -->
  <!-- <annotationProcessor>org.checkerframework.checker.nullness.NullnessChecker</annotationProcessor> -->
  <!-- <annotationProcessor>org.checkerframework.checker.regex.RegexChecker</annotationProcessor> -->
  <annotationProcessor>org.checkerframework.checker.resourceleak.ResourceLeakChecker</annotationProcessor>
  <!-- <annotationProcessor>org.checkerframework.checker.signedness.SignednessChecker</annotationProcessor> -->
  <!-- <annotationProcessor>org.checkerframework.checker.tainting.TaintingChecker</annotationProcessor> -->
  <!-- <annotationProcessor>org.checkerframework.common.initializedfields.InitializedFieldsChecker</annotationProcessor> -->
  <!-- <annotationProcessor>org.checkerframework.framework.util.PurityChecker</annotationProcessor> -->
</annotationProcessors>

I can see the documentation is coming from a research perspective. Personally, I would appreciate more of an implementation perspective. I guess it boils down to who you want your audience to be.