Make our Javadoc validation a little stricter

I'm not sure there's much utility in this, but still feels worth doing.

build.gradle

@@ -68,7 +68,7 @@ configurations {
 }
 
 dependencies {
-    checkstyle "com.puppycrawl.tools:checkstyle:8.21"
+    checkstyle "com.puppycrawl.tools:checkstyle:8.25"
 
     deobfProvided "mezz.jei:jei_1.12.2:4.15.0.269:api"
     deobfProvided "pl.asie:Charset-Lib:0.5.4.6"

config/checkstyle/checkstyle.xml

@@ -14,9 +14,7 @@
         <!-- Annotations -->
         <module name="AnnotationLocation" />
         <module name="AnnotationUseStyle" />
-        <module name="MissingDeprecated">
+        <module name="MissingDeprecated" />
-            <property name="skipNoJavadoc" value="true" />
-        </module>
         <module name="MissingOverride" />
 
         <!-- Blocks -->
@@ -57,6 +55,9 @@
         <module name="SimplifyBooleanReturn" />
         <module name="StringLiteralEquality" />
         <module name="UnnecessaryParentheses" />
+        <module name="UnnecessarySemicolonAfterTypeMemberDeclaration" />
+        <module name="UnnecessarySemicolonInTryWithResources" />
+        <module name="UnnecessarySemicolonInEnumeration" />
 
         <!-- Imports -->
         <module name="CustomImportOrder" />
@@ -65,10 +66,16 @@
         <module name="UnusedImports" />
 
         <!-- Javadoc -->
+        <!-- TODO: Missing* checks for the dan200.computercraft.api package? -->
         <module name="AtclauseOrder" />
-        <!-- TODO: Cleanup our documentation before enabling JavadocMethod, JavadocStyle, JavadocType and SummaryJavadoc. -->
+        <module name="InvalidJavadocPosition" />
+        <module name="JavadocBlockTagLocation" />
+        <module name="JavadocMethod"/>
+        <module name="JavadocType"/>
+        <module name="JavadocStyle" />
         <module name="NonEmptyAtclauseDescription" />
         <module name="SingleLineJavadoc" />
+        <module name="SummaryJavadocCheck"/>
 
         <!-- Misc -->
         <module name="ArrayTypeStyle" />

config/checkstyle/suppressions.xml

@@ -6,4 +6,7 @@
     <!-- All the config options and method fields. -->
     <suppress checks="StaticVariableName" files=".*[\\/]ComputerCraft.java" />
     <suppress checks="StaticVariableName" files=".*[\\/]ComputerCraftAPI.java" />
+
+    <!-- Do not check for missing package Javadoc. -->
+    <suppress checks="JavadocStyle" files=".*[\\/]package-info.java" />
 </suppressions>

src/main/java/dan200/computercraft/api/ComputerCraftAPI.java

@@ -32,8 +32,9 @@ import java.lang.reflect.Method;
 
 /**
  * The static entry point to the ComputerCraft API.
- * Members in this class must be called after mod_ComputerCraft has been initialised,
+ *
- * but may be called before it is fully loaded.
+ * Members in this class must be called after mod_ComputerCraft has been initialised, but may be called before it is
+ * fully loaded.
  */
 public final class ComputerCraftAPI
 {
@@ -269,7 +270,7 @@ public final class ComputerCraftAPI
     }
 
     /**
-     * Registers a media provider to provide {@link IMedia} implementations for Items
+     * Registers a media provider to provide {@link IMedia} implementations for Items.
      *
      * @param provider The media provider to register.
      * @see IMediaProvider
@@ -370,7 +371,7 @@ public final class ComputerCraftAPI
     }
 
     /**
-     * Construct a new wired node for a given wired element
+     * Construct a new wired node for a given wired element.
      *
      * @param element The element to construct it for
      * @return The element's node
@@ -398,7 +399,7 @@ public final class ComputerCraftAPI
     }
 
     /**
-     * Get the wired network element for a block in world
+     * Get the wired network element for a block in world.
      *
      * @param world The world the block exists in
      * @param pos   The position the block exists in

src/main/java/dan200/computercraft/api/filesystem/IMount.java

@@ -19,7 +19,7 @@ import java.util.List;
 
 /**
  * Represents a read only part of a virtual filesystem that can be mounted onto a computer using
- * {@link IComputerAccess#mount(String, IMount)}
+ * {@link IComputerAccess#mount(String, IMount)}.
  *
  * Ready made implementations of this interface can be created using
  * {@link ComputerCraftAPI#createSaveDirMount(World, String, long)} or
@@ -60,7 +60,7 @@ public interface IMount
     void list( @Nonnull String path, @Nonnull List<String> contents ) throws IOException;
 
     /**
-     * Returns the size of a file with a given path, in bytes
+     * Returns the size of a file with a given path, in bytes.
      *
      * @param path A file path in normalised format, relative to the mount location. ie: "programs/myprogram".
      * @return The size of the file, in bytes.

src/main/java/dan200/computercraft/api/lua/IComputerSystem.java

@@ -26,7 +26,7 @@ public interface IComputerSystem extends IComputerAccess
     IFileSystem getFileSystem();
 
     /**
-     * Get the label for this computer
+     * Get the label for this computer.
      *
      * @return This computer's label, or {@code null} if it is not set.
      */

src/main/java/dan200/computercraft/api/pocket/IPocketAccess.java

@@ -16,7 +16,7 @@ import javax.annotation.Nullable;
 import java.util.Map;
 
 /**
- * Wrapper class for pocket computers
+ * Wrapper class for pocket computers.
  */
 public interface IPocketAccess
 {

src/main/java/dan200/computercraft/api/turtle/TurtleSide.java

@@ -12,12 +12,12 @@ package dan200.computercraft.api.turtle;
 public enum TurtleSide
 {
     /**
-     * The turtle's left side (where the pickaxe usually is on a Wireless Mining Turtle)
+     * The turtle's left side (where the pickaxe usually is on a Wireless Mining Turtle).
      */
     Left,
 
     /**
-     * The turtle's right side (where the modem usually is on a Wireless Mining Turtle)
+     * The turtle's right side (where the modem usually is on a Wireless Mining Turtle).
      */
     Right,
 }

src/main/java/dan200/computercraft/api/turtle/TurtleVerb.java

@@ -18,12 +18,12 @@ import net.minecraft.util.EnumFacing;
 public enum TurtleVerb
 {
     /**
-     * The turtle called {@code turtle.dig()}, {@code turtle.digUp()} or {@code turtle.digDown()}
+     * The turtle called {@code turtle.dig()}, {@code turtle.digUp()} or {@code turtle.digDown()}.
      */
     Dig,
 
     /**
-     * The turtle called {@code turtle.attack()}, {@code turtle.attackUp()} or {@code turtle.attackDown()}
+     * The turtle called {@code turtle.attack()}, {@code turtle.attackUp()} or {@code turtle.attackDown()}.
      */
     Attack,
 }

src/main/java/dan200/computercraft/api/turtle/event/TurtleAction.java

@@ -71,7 +71,7 @@ public enum TurtleAction
     EQUIP,
 
     /**
-     * Inspect a block in world
+     * Inspect a block in world.
      *
      * @see TurtleBlockEvent.Inspect
      */

src/main/java/dan200/computercraft/api/turtle/event/TurtleBlockEvent.java

@@ -112,7 +112,7 @@ public abstract class TurtleBlockEvent extends TurtlePlayerEvent
         }
 
         /**
-         * Get the upgrade doing the digging
+         * Get the upgrade doing the digging.
          *
          * @return The upgrade doing the digging.
          */

src/main/java/dan200/computercraft/api/turtle/event/TurtleInventoryEvent.java

@@ -31,7 +31,7 @@ public abstract class TurtleInventoryEvent extends TurtleBlockEvent
     }
 
     /**
-     * Get the inventory being interacted with
+     * Get the inventory being interacted with.
      *
      * @return The inventory being interacted with, {@code null} if the item will be dropped to/sucked from the world.
      */

src/main/java/dan200/computercraft/client/render/ItemMapLikeRenderer.java

@@ -18,7 +18,7 @@ import net.minecraft.util.math.MathHelper;
 public abstract class ItemMapLikeRenderer
 {
     /**
-     * The main rendering method for the item
+     * The main rendering method for the item.
      *
      * @param stack The stack to render
      * @see ItemRenderer#renderMapFirstPerson(ItemStack)
@@ -87,7 +87,7 @@ public abstract class ItemMapLikeRenderer
     }
 
     /**
-     * Render an item in the middle of the screen
+     * Render an item in the middle of the screen.
      *
      * @param pitch         The pitch of the player
      * @param equipProgress The equip progress of this item

src/main/java/dan200/computercraft/client/render/ItemPocketRenderer.java

@@ -32,7 +32,7 @@ import static dan200.computercraft.client.gui.FixedWidthFontRenderer.*;
 import static dan200.computercraft.client.gui.GuiComputer.*;
 
 /**
- * Emulates map rendering for pocket computers
+ * Emulates map rendering for pocket computers.
  */
 @Mod.EventBusSubscriber( modid = ComputerCraft.MOD_ID, value = Side.CLIENT )
 public final class ItemPocketRenderer extends ItemMapLikeRenderer

src/main/java/dan200/computercraft/client/render/ItemPrintoutRenderer.java

@@ -23,7 +23,7 @@ import static dan200.computercraft.shared.media.items.ItemPrintout.LINES_PER_PAG
 import static dan200.computercraft.shared.media.items.ItemPrintout.LINE_MAX_LENGTH;
 
 /**
- * Emulates map and item-frame rendering for printouts
+ * Emulates map and item-frame rendering for printouts.
  */
 @Mod.EventBusSubscriber( modid = ComputerCraft.MOD_ID, value = Side.CLIENT )
 public final class ItemPrintoutRenderer extends ItemMapLikeRenderer

src/main/java/dan200/computercraft/client/render/PrintoutRenderer.java

@@ -28,32 +28,32 @@ public final class PrintoutRenderer
     private static final double BG_SIZE = 256.0;
 
     /**
-     * Width of a page
+     * Width of a page.
      */
     public static final int X_SIZE = 172;
 
     /**
-     * Height of a page
+     * Height of a page.
      */
     public static final int Y_SIZE = 209;
 
     /**
-     * Padding between the left and right of a page and the text
+     * Padding between the left and right of a page and the text.
      */
     public static final int X_TEXT_MARGIN = 13;
 
     /**
-     * Padding between the top and bottom of a page and the text
+     * Padding between the top and bottom of a page and the text.
      */
     public static final int Y_TEXT_MARGIN = 11;
 
     /**
-     * Width of the extra page texture
+     * Width of the extra page texture.
      */
     private static final int X_FOLD_SIZE = 12;
 
     /**
-     * Size of the leather cover
+     * Size of the leather cover.
      */
     public static final int COVER_SIZE = 12;
 

src/main/java/dan200/computercraft/client/render/TileEntityCableRenderer.java

@@ -97,6 +97,8 @@ public class TileEntityCableRenderer extends TileEntitySpecialRenderer<TileCable
     }
 
     /**
+     * Set up the state for rendering block-breaking progress.
+     *
      * @see RenderGlobal#preRenderDamagedBlocks()
      */
     private void preRenderDamagedBlocks()
@@ -115,6 +117,8 @@ public class TileEntityCableRenderer extends TileEntitySpecialRenderer<TileCable
     }
 
     /**
+     * Tear down the state for rendering block-breaking progress.
+     *
      * @see RenderGlobal#postRenderDamagedBlocks()
      */
     private void postRenderDamagedBlocks()

src/main/java/dan200/computercraft/core/apis/AddressPredicate.java

@@ -154,7 +154,7 @@ public class AddressPredicate
     }
 
     /**
-     * Determine whether the given address matches a series of patterns
+     * Determine whether the given address matches a series of patterns.
      *
      * @param address The address to check.
      * @return Whether it matches any of these patterns.

src/main/java/dan200/computercraft/core/apis/TableHelper.java

@@ -16,7 +16,7 @@ import java.util.Map;
 import static dan200.computercraft.api.lua.ArgumentHelper.getNumericType;
 
 /**
- * Various helpers for tables
+ * Various helpers for tables.
  */
 public final class TableHelper
 {

src/main/java/dan200/computercraft/core/apis/handles/HandleGeneric.java

@@ -47,7 +47,7 @@ public abstract class HandleGeneric implements ILuaObject
     }
 
     /**
-     * Shared implementation for various file handle types
+     * Shared implementation for various file handle types.
      *
      * @param channel The channel to seek in
      * @param args    The Lua arguments to process, like Lua's {@code file:seek}.

src/main/java/dan200/computercraft/core/apis/http/NetworkUtils.java

@@ -99,7 +99,7 @@ public final class NetworkUtils
     }
 
     /**
-     * Checks a host is allowed
+     * Checks a host is allowed.
      *
      * @param host The domain to check against
      * @throws HTTPRequestException If the host is not permitted.

src/main/java/dan200/computercraft/core/apis/http/Resource.java

@@ -20,6 +20,8 @@ import java.util.function.Consumer;
 
 /**
  * A holder for one or more resources, with a lifetime.
+ *
+ * @param <T> The type of this resource. Should be the class extending from {@link Resource}.
  */
 public abstract class Resource<T extends Resource<T>> implements Closeable
 {
@@ -42,8 +44,9 @@ public abstract class Resource<T extends Resource<T>> implements Closeable
     }
 
     /**
-     * Checks if this has been cancelled. If so, it'll clean up any
+     * Checks if this has been cancelled. If so, it'll clean up any existing resources and cancel any pending futures.
-     * existing resources and cancel any pending futures.
+     *
+     * @return Whether this resource has been closed.
      */
     public final boolean checkClosed()
     {
@@ -80,6 +83,7 @@ public abstract class Resource<T extends Resource<T>> implements Closeable
     /**
      * Create a {@link WeakReference} which will close {@code this} when collected.
      *
+     * @param <R>    The object we are wrapping in a reference.
      * @param object The object to reference to
      * @return The weak reference.
      */

src/main/java/dan200/computercraft/core/apis/http/ResourceGroup.java

@@ -14,6 +14,8 @@ import java.util.function.Supplier;
 
 /**
  * A collection of {@link Resource}s, with an upper bound on capacity.
+ *
+ * @param <T> The type of the resource this group manages.
  */
 public class ResourceGroup<T extends Resource<T>>
 {

src/main/java/dan200/computercraft/core/apis/http/ResourceQueue.java

@@ -12,6 +12,8 @@ import java.util.function.Supplier;
 
 /**
  * A {@link ResourceGroup} which will queue items when the group at capacity.
+ *
+ * @param <T> The type of the resource this queue manages.
  */
 public class ResourceQueue<T extends Resource<T>> extends ResourceGroup<T>
 {

src/main/java/dan200/computercraft/core/apis/http/request/HttpRequest.java

@@ -40,7 +40,7 @@ import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * Represents one or more
+ * Represents an in-progress HTTP request.
  */
 public class HttpRequest extends Resource<HttpRequest>
 {

src/main/java/dan200/computercraft/core/apis/http/request/HttpRequestHandler.java

@@ -226,7 +226,11 @@ public final class HttpRequestHandler extends SimpleChannelInboundHandler<HttpOb
     }
 
     /**
-     * Determine the redirect from this response
+     * Determine the redirect from this response.
+     *
+     * @param status  The status of the HTTP response.
+     * @param headers The headers of the HTTP response.
+     * @return The URI to redirect to, or {@code null} if no redirect should occur.
      */
     private URI getRedirect( HttpResponseStatus status, HttpHeaders headers )
     {

src/main/java/dan200/computercraft/core/computer/ComputerExecutor.java

@@ -268,7 +268,7 @@ final class ComputerExecutor
     }
 
     /**
-     * Queue an event if the computer is on
+     * Queue an event if the computer is on.
      *
      * @param event The event's name
      * @param args  The event's arguments

src/main/java/dan200/computercraft/core/computer/ComputerThread.java

@@ -50,7 +50,7 @@ import static dan200.computercraft.core.computer.TimeoutState.TIMEOUT;
 public final class ComputerThread
 {
     /**
-     * How often the computer thread monitor should run, in milliseconds
+     * How often the computer thread monitor should run, in milliseconds.
      *
      * @see Monitor
      */
@@ -83,7 +83,7 @@ public final class ComputerThread
     private static final Object threadLock = new Object();
 
     /**
-     * Whether the computer thread system is currently running
+     * Whether the computer thread system is currently running.
      */
     private static volatile boolean running = false;
 
@@ -105,7 +105,7 @@ public final class ComputerThread
     private static final Condition hasWork = computerLock.newCondition();
 
     /**
-     * Active queues to execute
+     * Active queues to execute.
      */
     private static final TreeSet<ComputerExecutor> computerQueue = new TreeSet<>( ( a, b ) -> {
         if( a == b ) return 0; // Should never happen, but let's be consistent here
@@ -126,7 +126,7 @@ public final class ComputerThread
     private ComputerThread() {}
 
     /**
-     * Start the computer thread
+     * Start the computer thread.
      */
     static void start()
     {
@@ -194,7 +194,7 @@ public final class ComputerThread
     }
 
     /**
-     * Mark a computer as having work, enqueuing it on the thread
+     * Mark a computer as having work, enqueuing it on the thread.
      *
      * You must be holding {@link ComputerExecutor}'s {@code queueLock} when calling this method - it should only
      * be called from {@code enqueue}.
@@ -244,6 +244,8 @@ public final class ComputerThread
      * {@link #minimumVirtualRuntime} based on the current tasks.
      *
      * This is called before queueing tasks, to ensure that {@link #minimumVirtualRuntime} is up-to-date.
+     *
+     * @param current The machine which we updating runtimes from.
      */
     private static void updateRuntimes( @Nullable ComputerExecutor current )
     {
@@ -321,7 +323,7 @@ public final class ComputerThread
     }
 
     /**
-     * The scaled period for a single task
+     * The scaled period for a single task.
      *
      * @return The scaled period for the task
      * @see #DEFAULT_LATENCY
@@ -336,7 +338,7 @@ public final class ComputerThread
     }
 
     /**
-     * Determine if the thread has computers queued up
+     * Determine if the thread has computers queued up.
      *
      * @return If we have work queued up.
      */

src/main/java/dan200/computercraft/core/computer/TimeoutState.java

@@ -36,12 +36,12 @@ import java.util.concurrent.TimeUnit;
 public final class TimeoutState
 {
     /**
-     * The total time a task is allowed to run before aborting in nanoseconds
+     * The total time a task is allowed to run before aborting in nanoseconds.
      */
     static final long TIMEOUT = TimeUnit.MILLISECONDS.toNanos( 7000 );
 
     /**
-     * The time the task is allowed to run after each abort in nanoseconds
+     * The time the task is allowed to run after each abort in nanoseconds.
      */
     static final long ABORT_TIMEOUT = TimeUnit.MILLISECONDS.toNanos( 1500 );
 
@@ -111,6 +111,8 @@ public final class TimeoutState
 
     /**
      * If the machine should be passively aborted.
+     *
+     * @return {@code true} if we should throw a timeout error.
      */
     public boolean isSoftAborted()
     {
@@ -118,7 +120,9 @@ public final class TimeoutState
     }
 
     /**
-     * If the machine should be forcibly aborted.
+     * Determine if the machine should be forcibly aborted.
+     *
+     * @return {@code true} if the machine should be forcibly shut down.
      */
     public boolean isHardAborted()
     {
@@ -146,7 +150,7 @@ public final class TimeoutState
     }
 
     /**
-     * Pauses the cumulative time, to be resumed by {@link #startTimer()}
+     * Pauses the cumulative time, to be resumed by {@link #startTimer()}.
      *
      * @see #nanoCumulative()
      */

src/main/java/dan200/computercraft/core/lua/MachineResult.java

@@ -38,7 +38,7 @@ public final class MachineResult
     public static final MachineResult TIMEOUT = new MachineResult( true, false, TimeoutState.ABORT_MESSAGE );
 
     /**
-     * An error with no user-friendly error message
+     * An error with no user-friendly error message.
      */
     public static final MachineResult GENERIC_ERROR = new MachineResult( true, false, null );
 

src/main/java/dan200/computercraft/core/terminal/Terminal.java

@@ -314,6 +314,9 @@ public class Terminal
     }
 
     /**
+     * Determine whether this terminal has changed.
+     *
+     * @return If this terminal is dirty.
      * @deprecated All {@code *Changed()} methods are deprecated: one should pass in a callback
      * instead.
      */

src/main/java/dan200/computercraft/shared/command/framework/CommandRoot.java

@@ -18,7 +18,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * A command which delegates to a series of sub commands
+ * A command which delegates to a series of sub commands.
  */
 public class CommandRoot implements ISubCommand
 {

src/main/java/dan200/computercraft/shared/command/framework/ISubCommand.java

@@ -22,7 +22,7 @@ import java.util.List;
 public interface ISubCommand
 {
     /**
-     * Get the name of this command
+     * Get the name of this command.
      *
      * @return The name of this command
      * @see ICommand#getName()
@@ -40,7 +40,7 @@ public interface ISubCommand
     String getFullName();
 
     /**
-     * Get the usage of this command
+     * Get the usage of this command.
      *
      * @param context The context this command is executed in
      * @return The usage of this command
@@ -62,16 +62,17 @@ public interface ISubCommand
     boolean checkPermission( @Nonnull CommandContext context );
 
     /**
-     * Execute this command
+     * Execute this command.
      *
      * @param context   The current command context.
-     * @param arguments The arguments passed  @throws CommandException When an error occurs
+     * @param arguments The arguments passed
+     * @throws CommandException When an error occurs
      * @see ICommand#execute(MinecraftServer, ICommandSender, String[])
      */
     void execute( @Nonnull CommandContext context, @Nonnull List<String> arguments ) throws CommandException;
 
     /**
-     * Get a list of possible completions
+     * Get a list of possible completions.
      *
      * @param context   The current command context.
      * @param arguments The arguments passed. You should complete the last one.

src/main/java/dan200/computercraft/shared/command/text/ChatHelpers.java

@@ -15,7 +15,7 @@ import net.minecraft.util.text.event.ClickEvent;
 import net.minecraft.util.text.event.HoverEvent;
 
 /**
- * Various helpers for building chat messages
+ * Various helpers for building chat messages.
  */
 public final class ChatHelpers
 {

src/main/java/dan200/computercraft/shared/command/text/TableBuilder.java

@@ -107,7 +107,7 @@ public class TableBuilder
     }
 
     /**
-     * Trim this table to a given height
+     * Trim this table to a given height.
      *
      * @param height The desired height.
      */

src/main/java/dan200/computercraft/shared/command/text/TableFormatter.java

@@ -22,7 +22,7 @@ public interface TableFormatter
     ITextComponent HEADER = coloured( "=", TextFormatting.GRAY );
 
     /**
-     * Get additional padding for the component
+     * Get additional padding for the component.
      *
      * @param component The component to pad
      * @param width     The desired width for the component
@@ -32,7 +32,7 @@ public interface TableFormatter
     ITextComponent getPadding( ITextComponent component, int width );
 
     /**
-     * Get the minimum padding between each column
+     * Get the minimum padding between each column.
      *
      * @return The minimum padding.
      */

src/main/java/dan200/computercraft/shared/computer/blocks/TileComputerBase.java

@@ -280,7 +280,7 @@ public abstract class TileComputerBase extends TileGeneric implements IComputerT
     }
 
     /**
-     * Gets the redstone input for an adjacent block
+     * Gets the redstone input for an adjacent block.
      *
      * @param world The world we exist in
      * @param pos   The position of the neighbour

src/main/java/dan200/computercraft/shared/computer/core/InputHandler.java

@@ -7,7 +7,7 @@
 package dan200.computercraft.shared.computer.core;
 
 /**
- * Receives some input and forwards it to a computer
+ * Receives some input and forwards it to a computer.
  *
  * @see InputState
  * @see IComputer

src/main/java/dan200/computercraft/shared/integration/jei/JEIComputerCraft.java

@@ -108,7 +108,7 @@ public class JEIComputerCraft implements IModPlugin
     }
 
     /**
-     * Distinguishes turtles by upgrades and family
+     * Distinguishes turtles by upgrades and family.
      */
     private static final ISubtypeInterpreter turtleSubtype = stack -> {
         Item item = stack.getItem();
@@ -132,7 +132,7 @@ public class JEIComputerCraft implements IModPlugin
     };
 
     /**
-     * Distinguishes pocket computers by upgrade and family
+     * Distinguishes pocket computers by upgrade and family.
      */
     private static final ISubtypeInterpreter pocketSubtype = stack -> {
         Item item = stack.getItem();
@@ -152,7 +152,7 @@ public class JEIComputerCraft implements IModPlugin
     };
 
     /**
-     * Distinguishes disks by colour
+     * Distinguishes disks by colour.
      */
     private static final ISubtypeInterpreter diskSubtype = stack -> {
         Item item = stack.getItem();

src/main/java/dan200/computercraft/shared/media/items/RecordMedia.java

@@ -15,7 +15,7 @@ import net.minecraft.util.SoundEvent;
 import javax.annotation.Nonnull;
 
 /**
- * An implementation of IMedia for ItemRecord's
+ * An implementation of IMedia for ItemRecords.
  */
 public final class RecordMedia implements IMedia
 {

src/main/java/dan200/computercraft/shared/network/NetworkHandler.java

@@ -72,6 +72,7 @@ public final class NetworkHandler
      * /**
      * Register packet, and a thread-unsafe handler for it.
      *
+     * @param <T>     The type of the packet to send.
      * @param id      The identifier for this packet type
      * @param side    The side to register this packet handler under
      * @param factory The factory for this type of packet.

src/main/java/dan200/computercraft/shared/peripheral/modem/WirelessModemPeripheral.java

@@ -7,8 +7,11 @@
 package dan200.computercraft.shared.peripheral.modem;
 
 /**
- * This only exists for backwards compatibility
+ * This only exists for backwards compatibility.
+ *
+ * @deprecated Use {@link dan200.computercraft.shared.peripheral.modem.wireless.WirelessModemPeripheral} instead.
  */
+@Deprecated
 public abstract class WirelessModemPeripheral extends dan200.computercraft.shared.peripheral.modem.wireless.WirelessModemPeripheral
 {
     @Deprecated

src/main/java/dan200/computercraft/shared/peripheral/modem/wired/WiredModemLocalPeripheral.java

@@ -23,7 +23,7 @@ import java.util.Collections;
 import java.util.Map;
 
 /**
- * Represents a local peripheral exposed on the wired network
+ * Represents a local peripheral exposed on the wired network.
  *
  * This is responsible for getting the peripheral in world, tracking id and type and determining whether
  * it has changed.
@@ -39,7 +39,7 @@ public final class WiredModemLocalPeripheral
     private IPeripheral peripheral;
 
     /**
-     * Attach a new peripheral from the world
+     * Attach a new peripheral from the world.
      *
      * @param world     The world to search in
      * @param origin    The position to search from
@@ -76,7 +76,7 @@ public final class WiredModemLocalPeripheral
     }
 
     /**
-     * Detach the current peripheral
+     * Detach the current peripheral.
      *
      * @return Whether the peripheral changed
      */

src/main/java/dan200/computercraft/shared/turtle/core/TurtlePlayer.java

@@ -37,7 +37,7 @@ public class TurtlePlayer extends FakePlayer
     );
 
     /**
-     * Construct a TurtlePlayer which exists in the world
+     * Construct a TurtlePlayer which exists in the world.
      *
      * @param world The world the player exists in
      * @deprecated This is required by {@link Entity}.

src/main/java/dan200/computercraft/shared/util/StringUtil.java

@@ -6,6 +6,8 @@
 
 package dan200.computercraft.shared.util;
 
+import net.minecraft.util.text.TextComponentTranslation;
+
 public final class StringUtil
 {
     private StringUtil() {}
@@ -33,7 +35,12 @@ public final class StringUtil
     }
 
     /**
-     * Translates a Stat name
+     * Translates a string.
+     *
+     * Try to avoid using this where possible - it is generally preferred to use {@link TextComponentTranslation}.
+     *
+     * @param key The key to translate.
+     * @return The translated string.
      */
     @SuppressWarnings( "deprecation" )
     public static String translate( String key )
@@ -42,12 +49,18 @@ public final class StringUtil
     }
 
     /**
-     * Translates a Stat name with format args
+     * Translates and formats a string.
+     *
+     * Try to avoid using this where possible - it is generally preferred to use {@link TextComponentTranslation}.
+     *
+     * @param key  The key to translate.
+     * @param args The arguments to supply to {@link String#format(String, Object...)}.
+     * @return The translated and formatted string.
      */
     @SuppressWarnings( "deprecation" )
-    public static String translateFormatted( String key, Object... format )
+    public static String translateFormatted( String key, Object... args )
     {
-        return net.minecraft.util.text.translation.I18n.translateToLocalFormatted( key, format );
+        return net.minecraft.util.text.translation.I18n.translateToLocalFormatted( key, args );
     }
 
     public static byte[] encodeString( String string )

src/main/java/dan200/computercraft/shared/util/ThreadUtils.java

@@ -12,7 +12,7 @@ import dan200.computercraft.ComputerCraft;
 import java.util.concurrent.ThreadFactory;
 
 /**
- * Provides some utilities to create thread groups
+ * Provides some utilities to create thread groups.
  */
 public final class ThreadUtils
 {
@@ -33,7 +33,7 @@ public final class ThreadUtils
     }
 
     /**
-     * Construct a group under ComputerCraft's shared group
+     * Construct a group under ComputerCraft's shared group.
      *
      * @param name The group's name. This will be prefixed with "ComputerCraft-".
      * @return The constructed thread group.