Clean up Javadocs, more enforcing of NonNull arguments

Author: onebeastchris

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraData.java

@@ -27,29 +27,36 @@
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.geyser.api.connection.GeyserConnection;
 
 import java.util.Set;
 import java.util.UUID;
 
+/**
+ * This interface holds all the methods that relate to a client's camera.
+ * Can be accessed through {@link GeyserConnection#camera()}.
+ */
 public interface CameraData {
 
     /**
-     * Sends a camera instruction to the client.
+     * Sends a camera fade instruction to the client.
      * If an existing camera fade is already in progress, the current fade will be prolonged.
      * Can be built using {@link CameraFade.Builder}.
+     * To stop a fade early, use {@link #clearCameraInstructions()}.
      *
-     * @param fade the camera fade to send
+     * @param fade the camera fade instruction to send
      */
     void sendCameraFade(@NonNull CameraFade fade);
 
     /**
-     * Sends a camera instruction to the client.
-     * If an existing camera movement is already in progress:
-     * The (optional) camera fade will be added on top of the existing fade, and
-     * the final camera position will be the one of the latest instruction.
+     * Sends a camera position instruction to the client.
+     * If an existing camera movement is already in progress,
+     * the final camera position will be the one of the latest instruction, and
+     * the (optional) camera fade will be added on top of the existing fade.
      * Can be built using {@link CameraPosition.Builder}.
+     * To stop reset the camera position/stop ongoing instructions, use {@link #clearCameraInstructions()}.
      *
-     * @param position the camera position to send
+     * @param position the camera position instruction to send
      */
     void sendCameraPosition(@NonNull CameraPosition position);
 
@@ -60,8 +67,8 @@ public interface CameraData {
     void clearCameraInstructions();
 
     /**
-     * Forces a {@link CameraPerspective} on the client. This will prevent
-     * the client from changing their camera perspective until it is unlocked via {@link #clearCameraInstructions()}.
+     * Forces a {@link CameraPerspective} on the client. This will prevent the client
+     * from changing their camera perspective until it is unlocked via {@link #clearCameraInstructions()}.
      * <p>
      * Note: You cannot force a client into a free camera perspective with this method.
      * To do that, send a {@link CameraPosition} via {@link #sendCameraPosition(CameraPosition)} - it requires a set position
@@ -72,16 +79,17 @@ public interface CameraData {
     void forceCameraPerspective(@NonNull CameraPerspective perspective);
 
     /**
-     * Gets the client's current {@link CameraPerspective}, if forced.
+     * Gets the client's current {@link CameraPerspective}, if one is currently forced.
      * This will return {@code null} if the client is not currently forced into a perspective.
-     * If a perspective is forced, the client will not be able to change their camera perspective until it is unlocked
+     * If a perspective is forced, the client will not be able to change their camera perspective until it is unlocked.
      *
      * @return the forced perspective, or {@code null} if none is forced.
      */
     @Nullable CameraPerspective forcedCameraPerspective();
 
     /**
-     * Shakes the client's camera.<br><br>
+     * Shakes the client's camera.
+     * <p>
      * If the camera is already shaking with the same {@link CameraShake} type, then the additional intensity
      * will be layered on top of the existing intensity, with their own distinct durations.<br>
      * If the existing shake type is different and the new intensity/duration are not positive, the existing shake only
@@ -94,7 +102,7 @@ public interface CameraData {
     void shakeCamera(float intensity, float duration, @NonNull CameraShake type);
 
     /**
-     * Stops all camera shake of any type.
+     * Stops all camera shakes of any type.
      */
     void stopCameraShake();
 
@@ -123,18 +131,18 @@ public interface CameraData {
     /**
      * (Un)locks the client's camera, so that they cannot look around.
      * To ensure the camera is only unlocked when all locks are released, you must supply
-     * a UUID-key to this method, and use the same key to unlock the camera.
+     * a UUID when using method, and use the same UUID to unlock the camera.
      *
      * @param lock whether to lock the camera
-     * @param owner the owner of the lock
+     * @param owner the owner of the lock, represented with a UUID
      * @return if the camera is locked after this method call
      */
     boolean lockCamera(boolean lock, @NonNull UUID owner);
 
     /**
      * Returns whether the client's camera is locked.
      *
-     * @return whether the camera is locked
+     * @return whether the camera is currently locked
      */
     boolean isCameraLocked();
 }

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraEaseType.java

@@ -25,6 +25,12 @@
 
 package org.geysermc.geyser.api.bedrock.camera;
 
+/**
+ * These are all the easing types that can be used when sending a {@link CameraPosition} instruction.
+ * When using these, the client won't teleport to the new camera position, but instead transition to it.
+ * <p>
+ * See <a href="https://easings.net/">https://easings.net/</a>.</a> for more information.
+ */
 public enum CameraEaseType {
     LINEAR("linear"),
     SPRING("spring"),

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraFade.java

@@ -33,6 +33,8 @@
 
 /**
  * Represents a coloured fade overlay on the camera.
+ * <p>
+ * Can be sent with {@link CameraData#sendCameraFade(CameraFade)}, or with a {@link CameraPosition} instruction.
  */
 public interface CameraFade {
 

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraPosition.java

@@ -31,6 +31,15 @@
 import org.cloudburstmc.math.vector.Vector3f;
 import org.geysermc.geyser.api.GeyserApi;
 
+/**
+ * This interface represents a camera position instruction. Can be built with the {@link #builder()}.
+ * <p>
+ * Any camera position instruction pins the client camera to a specific position and rotation.
+ * You can set {@link CameraEaseType} to ensure a smooth transition that will last {@link #easeDuration()} seconds.
+ * A {@link CameraFade} can also be sent, which will transition the player to a coloured transition during the transition.
+ * <p>
+ * Use {@link CameraData#sendCameraPosition(CameraPosition)} to send such an instruction to any connection.
+ */
 public interface CameraPosition {
 
     /**

api/src/main/java/org/geysermc/geyser/api/bedrock/camera/CameraShake.java

@@ -25,6 +25,9 @@
 
 package org.geysermc.geyser.api.bedrock.camera;
 
+/**
+ * Represents a camera shake instruction. Can be sent in {@link CameraData#shakeCamera(float, float, CameraShake)}
+ */
 public enum CameraShake {
     POSITIONAL,
     ROTATIONAL

api/src/main/java/org/geysermc/geyser/api/entity/EntityData.java

@@ -28,15 +28,22 @@
 import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.geyser.api.connection.GeyserConnection;
 import org.geysermc.geyser.api.entity.type.GeyserEntity;
 import org.geysermc.geyser.api.entity.type.player.GeyserPlayerEntity;
 
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * This class holds all the methods that relate to entities.
+ * Can be accessed through {@link GeyserConnection#entities()}.
+ */
 public interface EntityData {
 
     /**
+     * Returns a {@link GeyserEntity} to e.g. make them play an emote.
+     *
      * @param javaId the Java entity ID to look up.
      * @return a {@link GeyserEntity} if present in this connection's entity tracker.
      */
@@ -51,7 +58,7 @@ public interface EntityData {
     void showEmote(@NonNull GeyserPlayerEntity emoter, @NonNull String emoteId);
 
     /**
-     * Returns the {@link GeyserPlayerEntity} of this connection.
+     * Gets the {@link GeyserPlayerEntity} of this connection.
      *
      * @return the {@link GeyserPlayerEntity} of this connection.
      */
@@ -60,18 +67,18 @@ public interface EntityData {
     /**
      * (Un)locks the client's movement inputs, so that they cannot move.
      * To ensure that movement is only unlocked when all locks are released, you must supply
-     * a UUID-key to this method, and use the same key to unlock the camera.
+     * a UUID with this method, and use the same UUID to unlock the camera.
      *
-     * @param lock whether to lock the camera
+     * @param lock whether to lock the movement
      * @param owner the owner of the lock
      * @return if the movement is locked after this method call
      */
     boolean lockMovement(boolean lock, @NonNull UUID owner);
 
     /**
-     * Returns whether the client's camera is locked.
+     * Returns whether the client's movement is currently locked.
      *
-     * @return whether the camera is locked
+     * @return whether the movement is locked
      */
     boolean isMovementLocked();
 }

core/src/main/java/org/geysermc/geyser/impl/camera/GeyserCameraFade.java

@@ -36,8 +36,8 @@ public record GeyserCameraFade(
         float fadeInSeconds,
         float holdSeconds,
         float fadeOutSeconds
-) implements CameraFade {
 
+) implements CameraFade {
     public static class Builder implements CameraFade.Builder {
         private Color color;
         private float fadeInSeconds;
@@ -46,6 +46,10 @@ public static class Builder implements CameraFade.Builder {
 
         @Override
         public CameraFade.Builder color(@NonNull Color color) {
+            //noinspection ConstantValue
+            if (color == null) {
+                throw new IllegalArgumentException("Color cannot be null!");
+            }
             this.color = color;
             return this;
         }

core/src/main/java/org/geysermc/geyser/impl/camera/GeyserCameraPosition.java

@@ -82,14 +82,15 @@ public CameraPosition.Builder easeType(@Nullable CameraEaseType easeType) {
         @Override
         public CameraPosition.Builder easeDuration(float easeDuration) {
             if (easeDuration < 0) {
-                throw new IllegalArgumentException("Camera ease duration cannot be negative");
+                throw new IllegalArgumentException("Camera ease duration cannot be negative!");
             }
             this.easeDuration = easeDuration;
             return this;
         }
 
         @Override
         public CameraPosition.Builder position(@NonNull Vector3f position) {
+            //noinspection ConstantValue
             if (position == null) {
                 throw new IllegalArgumentException("Camera position cannot be null");
             }
@@ -99,6 +100,9 @@ public CameraPosition.Builder position(@NonNull Vector3f position) {
 
         @Override
         public CameraPosition.Builder rotationX(int rotationX) {
+            if (rotationX < -90 || rotationX > 90) {
+                throw new IllegalArgumentException("X-axis rotation needs to be between -90 and 90 degrees.");
+            }
             this.rotationX = rotationX;
             return this;
         }