Cleanup javadoc, force UTF-8 encoding in Javadoc tasks (#938)

Make `check` depend on javadoc task to enforce proper javadocs

Author: SamCarlberg

annotation/src/main/java/edu/wpi/grip/annotation/operation/Description.java

@@ -19,30 +19,40 @@
 
   /**
    * The name of the operation being described.
+   *
+   * @return the name of the operation
    */
   String name();
 
   /**
    * A brief summary of the operation. In-depth descriptions, usage guides, and examples
    * should be on the wiki, not here.
+   *
+   * @return a summary of the operation
    */
   String summary();
 
   /**
    * The category the operation belongs to. Defaults to
    * {@link OperationCategory#MISCELLANEOUS MISCELLANEOUS}.
+   *
+   * @return the category to which the operation belongs
    */
   OperationCategory category() default MISCELLANEOUS;
 
   /**
    * All known aliases of the operation. If the name of the operation changes, the previous name
    * should be here. Defaults to an empty array.
+   *
+   * @return known aliases
    */
   String[] aliases() default {};
 
   /**
    * The name of the icon to use to display the operation. If empty ({@code ""}), no icon will be
    * shown. The icon should be located in {@code /edu/wpi/grip/ui/icons/}.
+   *
+   * @return the name of the icon
    */
   String iconName() default "";
 

build.gradle.kts

@@ -149,6 +149,11 @@ javaSubprojects {
 
     tasks.withType<Javadoc> {
         source(tasks.named<JavaCompile>("compileJava").map { it.source })
+        options.encoding = "UTF-8"
+    }
+
+    tasks.named("check").configure {
+        dependsOn("javadoc")
     }
 
     tasks.withType<JavaCompile>().configureEach {

core/src/main/java/edu/wpi/grip/core/Source.java

@@ -46,7 +46,7 @@ protected Source(ExceptionWitness.Factory exceptionWitnessFactory) {
   /**
    * Get the sockets for this source.
    *
-   * @return @return An array of {@link OutputSocket}s for the outputs that the source produces.
+   * @return An array of {@link OutputSocket}s for the outputs that the source produces.
    */
   public final ImmutableList<OutputSocket> getOutputSockets() {
     final List<OutputSocket> outputSockets = createOutputSockets();
@@ -83,6 +83,8 @@ protected ExceptionWitness getExceptionWitness() {
    * Initializes the source. This should not try to handle initialization exceptions. Instead, the
    * {@link #initializeSafely()} should report the problem with initializing to the exception
    * witness.
+   *
+   * @throws IOException if the source could not be initialized
    */
   public abstract void initialize() throws IOException;
 

core/src/main/java/edu/wpi/grip/core/http/PedanticHandler.java

@@ -66,6 +66,8 @@ public final void handle(String target,
    * @param baseRequest the base HTTP request
    * @param request     the request after being wrapped or filtered by other handlers
    * @param response    the HTTP response to send to the client
+   * @throws IOException      if an I/O error occurred while handling the request
+   * @throws ServletException if the request could not be handled
    * @see AbstractHandler#handle(String, Request, HttpServletRequest, HttpServletResponse)
    */
   protected abstract void handleIfPassed(String target,

core/src/main/java/edu/wpi/grip/core/serialization/Project.java

@@ -83,6 +83,8 @@ public void setFile(Optional<File> file) {
 
   /**
    * Load the project from a file.
+   *
+   * @throws IOException if the project file could not be read
    */
   public void open(File file) throws IOException {
     try (InputStreamReader reader = new InputStreamReader(new FileInputStream(file),
@@ -138,6 +140,8 @@ public boolean trySave(File file) {
 
   /**
    * Save the project to a file.
+   *
+   * @throws IOException if the file could not written
    */
   public void save(File file) throws IOException {
     try (Writer writer = new OutputStreamWriter(new FileOutputStream(file),