Add javac plugin for detecting common error cases at compile time (#8196)

Adds a `@NoDiscard` annotation that can be placed on methods to guarantee their return values are used and on types to guarantee that any method returning that type uses the return value.

Methods that call `@NoDiscard`-annotated functions can add a `@SuppressWarnings("NoDiscard")` or `@SuppressWarnings("all")` annotation (or annotation on the class declaring that method) to silence the compiler error warnings.

wpiannotations/BUILD.bazel

@@ -0,0 +1,8 @@
+load("@rules_java//java:defs.bzl", "java_library")
+
+java_library(
+    name = "wpiannotations",
+    srcs = glob(["src/main/java/**/*.java"]),
+    visibility = ["//visibility:public"],
+    deps = [],
+)

wpiannotations/CMakeLists.txt

@@ -0,0 +1,37 @@
+project(wpiannotations)
+
+# Java bindings
+if(WITH_JAVA)
+    include(UseJava)
+
+    file(GLOB_RECURSE JAVA_SOURCES src/main/java/*.java)
+
+    add_jar(
+        wpiannotations_jar
+        ${JAVA_SOURCES}
+        OUTPUT_NAME wpiannotations
+        OUTPUT_DIR ${WPILIB_BINARY_DIR}/${java_lib_dest}
+    )
+    set_property(TARGET wpiannotations_jar PROPERTY FOLDER "java")
+
+    install_jar(wpiannotations_jar DESTINATION ${java_lib_dest})
+    install_jar_exports(
+        TARGETS wpiannotations_jar
+        FILE wpiannotations.cmake
+        DESTINATION share/wpiannotations
+    )
+    install(FILES wpiannotations-config.cmake DESTINATION share/wpiannotations)
+endif()
+
+if(WITH_JAVA_SOURCE)
+    include(UseJava)
+    include(CreateSourceJar)
+    add_source_jar(
+        wpiannotations_src_jar
+        BASE_DIRECTORIES ${CMAKE_CURRENT_SOURCE_DIR}/src/main/java
+        OUTPUT_NAME wpiannotations-sources
+    )
+    set_property(TARGET wpiannotations_src_jar PROPERTY FOLDER "java")
+
+    install_jar(wpiannotations_src_jar DESTINATION ${java_lib_dest})
+endif()

wpiannotations/build.gradle

@@ -0,0 +1,11 @@
+ext {
+    useJava = true
+    useCpp = false
+    baseId = 'annotations'
+    groupId = 'org.wpilib'
+
+    nativeName = ''
+    devMain = ''
+}
+
+apply from: "${rootDir}/shared/java/javacommon.gradle"

wpiannotations/src/main/java/org/wpilib/annotation/NoDiscard.java

@@ -0,0 +1,27 @@
+// Copyright (c) FIRST and other WPILib contributors.
+// Open Source Software; you can modify and/or share it under the terms of
+// the WPILib BSD license file in the root directory of this project.
+
+package org.wpilib.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a method as returning a value that must be used. The WPILib compiler plugin will check for
+ * uses of methods with this annotation and report a compiler error if the value is unused. Marking
+ * a class or interface as {@code @NoDiscard} will act as if any method that returns that type or
+ * any subclass or implementor of that type has been marked with {@code @NoDiscard}.
+ */
+@Target({ElementType.METHOD, ElementType.TYPE})
+@Retention(RetentionPolicy.CLASS) // needs to be stored in the class for use by libraries
+public @interface NoDiscard {
+  /**
+   * An error message to display if the return value is not used.
+   *
+   * @return The error message.
+   */
+  String value() default "";
+}

wpiannotations/wpiannotations-config.cmake

@@ -0,0 +1,2 @@
+get_filename_component(SELF_DIR "${CMAKE_CURRENT_LIST_FILE}" PATH)
+include(${SELF_DIR}/wpiannotations.cmake)