Merge pull request #148 from Gaming32/javadocs

Add javadocs to the entire plugin system

src/main/java/io/github/gaming32/worldhost/plugin/FriendAdder.java

@@ -4,7 +4,13 @@
 
 import java.util.function.Consumer;
 
+/**
+ * Manages adding friends with the add friends screen.
+ */
 public interface FriendAdder {
+    /**
+     * A descriptive label for this {@link FriendAdder}. Typically, this matches the plugin's name.
+     */
     Component label();
 
     /**

src/main/java/io/github/gaming32/worldhost/plugin/FriendListFriend.java

@@ -5,21 +5,42 @@
 
 import java.util.Optional;
 
+/**
+ * Represents a friend to display in the friend list or on the add friend screen.
+ */
 public interface FriendListFriend extends Profilable {
     /**
      * Handles adding a friend. This should only be overridden if you implement a {@link FriendAdder}.
+     * @param refresher {@link Runnable} to invoke when adding is complete. This may be called from any thread.
      */
     default void addFriend(boolean notify, Runnable refresher) {
     }
 
+    /**
+     * Whether this friend supports the ability to toggle sending a notification when they are added. Even if this
+     * returns {@code true}, the notification need not be shown if the user receiving the friend request disables such
+     * notifications.
+     */
     default boolean supportsNotifyAdd() {
         return false;
     }
 
+    /**
+     * Removes this friend from the friend list.
+     * @param refresher {@link Runnable} to invoke when removal is complete. This may be called from any thread.
+     */
     void removeFriend(Runnable refresher);
 
+    /**
+     * Displays friend information in some capacity. This may be displaying an info screen or opening a webpage.
+     * @param parentScreen The screen to return to if the user closes a screen you open for this purpose.
+     */
     void showFriendInfo(Screen parentScreen);
 
+    /**
+     * A "tag" to show next to the friend's name, if any. If specified, the friend's name will be displayed as
+     * "Username (Tag)".
+     */
     default Optional<Component> tag() {
         return Optional.empty();
     }

src/main/java/io/github/gaming32/worldhost/plugin/InfoTextsCategory.java

@@ -1,6 +1,20 @@
 package io.github.gaming32.worldhost.plugin;
 
+/**
+ * Represents a category on which to display info texts.
+ *
+ * @see WorldHostPlugin#getInfoTexts
+ */
 public enum InfoTextsCategory {
+    /**
+     * Text to display on the friends list screen. The text will be displayed at the bottom of the screen, above the
+     * buttons.
+     */
     FRIENDS_SCREEN,
-    ONLINE_FRIENDS_SCREEN
+
+    /**
+     * Text to display on the online friends screen. The text will be displayed at the bottom of the screen, above the
+     * buttons.
+     */
+    ONLINE_FRIENDS_SCREEN,
 }

src/main/java/io/github/gaming32/worldhost/plugin/Joinability.java

@@ -2,26 +2,50 @@
 
 import net.minecraft.ChatFormatting;
 import net.minecraft.network.chat.Component;
+import net.minecraft.network.chat.MutableComponent;
 import net.minecraft.network.chat.Style;
 import org.jetbrains.annotations.NotNull;
 
 import java.util.Optional;
 import java.util.function.UnaryOperator;
 
+/**
+ * Represents the joinability of a friend.
+ */
 public sealed interface Joinability extends Comparable<Joinability> {
+    /**
+     * The reason, if specified.
+     */
     Optional<Component> reason();
 
+    /**
+     * The formatting for this joinability. Typically passed into
+     * {@link MutableComponent#withStyle(UnaryOperator) MutableComponent.withStyle}.
+     */
     UnaryOperator<Style> nameFormatting();
 
+    /**
+     * Whether this joinability is joinable.
+     */
     boolean canJoin();
 
+    /**
+     * The ordinal of this type of joinability. Mirrors {@link Enum#ordinal() Enum.ordinal}.
+     */
     int ordinal();
 
+    /**
+     * Compares this joinability's type to {@code o}. Mirrors {@link Enum#compareTo}. The {@link #reason} is ignored.
+     */
     @Override
     default int compareTo(@NotNull Joinability o) {
         return ordinal() - o.ordinal();
     }
 
+    /**
+     * Represents an unjoinable friend.
+     * @param reason The reason why the friend cannot be joined
+     */
     record Unjoinable(Optional<Component> reason) implements Joinability {
         public Unjoinable(Component reason) {
             this(Optional.of(reason));
@@ -47,6 +71,10 @@ public boolean canJoin() {
         }
     }
 
+    /**
+     * Represents a friend that can be joined, but potentially unstably.
+     * @param reason The reason why joining this friend may be unstable.
+     */
     record JoinableWithWarning(Optional<Component> reason) implements Joinability {
         public JoinableWithWarning(Component reason) {
             this(Optional.of(reason));
@@ -72,7 +100,13 @@ public boolean canJoin() {
         }
     }
 
+    /**
+     * Represents a friend that can be joined without any major issue.
+     */
     final class Joinable implements Joinability {
+        /**
+         * The sole instance of {@link Joinable}.
+         */
         public static final Joinable INSTANCE = new Joinable();
 
         private Joinable() {

src/main/java/io/github/gaming32/worldhost/plugin/OnlineFriend.java

@@ -1,19 +1,39 @@
 package io.github.gaming32.worldhost.plugin;
 
 import io.github.gaming32.worldhost.SecurityLevel;
-import net.minecraft.client.gui.screens.Screen;
-
+import io.github.gaming32.worldhost.config.WorldHostConfig;
 import java.util.UUID;
+import net.minecraft.client.gui.screens.Screen;
 
+/**
+ * Represents a friend that is currently online, to be shown in the online friends list.
+ */
 public interface OnlineFriend extends Profilable {
+    /**
+     * The friend's UUID.
+     */
     UUID uuid();
 
+    /**
+     * The security level of this friend. I.e. the confidence that this friend is who they say they are. Security
+     * levels below {@link SecurityLevel#SECURE SECURE} will display their security level in the UI. Note that this
+     * method does not deal with filtering based on {@link WorldHostConfig#getRequiredSecurityLevel the config}.
+     * Filtering must be done manually in {@link WorldHostPlugin#refreshOnlineFriends}.
+     */
     default SecurityLevel security() {
         return SecurityLevel.SECURE;
     }
 
+    /**
+     * Joins this friend's world.
+     * @param parentScreen The screen to return to if the user closes your screen.
+     */
     void joinWorld(Screen parentScreen);
 
+    /**
+     * Returns the {@link Joinability joinability} of this friend. {@link #joinWorld} will not be called on an
+     * unjoinable friend.
+     */
     default Joinability joinability() {
         return Joinability.Joinable.INSTANCE;
     }

src/main/java/io/github/gaming32/worldhost/plugin/Profilable.java

@@ -2,8 +2,18 @@
 
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * Represents an object that can be resolved into a {@link ProfileInfo}.
+ */
 public interface Profilable {
+    /**
+     * A {@link ProfileInfo} that is definitely ready now, and may be used before {@link #profileInfo} is complete.
+     */
     ProfileInfo fallbackProfileInfo();
 
+    /**
+     * Begin resolving a full {@link ProfileInfo}. {@link #fallbackProfileInfo} may be used before the returned
+     * {@link CompletableFuture} completes.
+     */
     CompletableFuture<ProfileInfo> profileInfo();
 }

src/main/java/io/github/gaming32/worldhost/plugin/ProfileInfo.java

@@ -2,11 +2,23 @@
 
 import io.github.gaming32.worldhost.toast.IconRenderer;
 
+/**
+ * Represents basic information about a user profile.
+ */
 public interface ProfileInfo {
+    /**
+     * The display name of the user.
+     */
     String name();
 
+    /**
+     * The {@link IconRenderer} used to display the user's icon.
+     */
     IconRenderer iconRenderer();
 
+    /**
+     * A basic implementation of {@link ProfileInfo} that holds values directly.
+     */
     record Basic(String name, IconRenderer iconRenderer) implements ProfileInfo {
     }
 }

src/main/java/io/github/gaming32/worldhost/plugin/WorldHostPlugin.java

@@ -1,7 +1,6 @@
 package io.github.gaming32.worldhost.plugin;
 
-import net.minecraft.network.chat.Component;
-
+import io.github.gaming32.worldhost.WorldHost;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -10,33 +9,60 @@
 import java.util.List;
 import java.util.Optional;
 import java.util.function.Consumer;
+import net.minecraft.network.chat.Component;
 
 /**
  * World Host plugin entrypoint class. On Forge and NeoForge, annotate your implementation with {@link Entrypoint}. On
  * Fabric, reference this class with the <a href="https://fabricmc.net/wiki/documentation:entrypoint">entrypoint</a>
  * {@code worldhost}.
  */
 public interface WorldHostPlugin {
+    /**
+     * Defines this plugin's priority. Plugins with a lower priority are run later.
+     */
     default int priority() {
         return 0;
     }
 
+    /**
+     * Initializes this plugin. This is called after all plugins have been discovered and respects
+     * {@link #priority plugin priority}.
+     */
     default void init() {
     }
 
+    /**
+     * Gets information text to display on the specified {@link InfoTextsCategory category}.
+     */
     default List<Component> getInfoTexts(InfoTextsCategory category) {
         return List.of();
     }
 
+    /**
+     * Pings the specified friends. The ping result should be placed in {@link WorldHost#ONLINE_FRIEND_PINGS}. Note
+     * that this method receives all {@link OnlineFriend}s, not just ones loaded by this plugin.
+     * @param friends The friends to ping
+     */
     default void pingFriends(Collection<OnlineFriend> friends) {
     }
 
+    /**
+     * Refreshes the list of online friends. The results should be handled by calling
+     * {@link WorldHost#friendWentOnline}.
+     */
     default void refreshOnlineFriends() {
     }
 
+    /**
+     * Lists the friends to show in the friends list.
+     * @param friendConsumer {@link Consumer} to invoke with every friend. This may be called from any thread.
+     */
     default void listFriends(Consumer<FriendListFriend> friendConsumer) {
     }
 
+    /**
+     * Returns a {@link FriendAdder} if this plugin supports adding friends.
+     */
     default Optional<FriendAdder> friendAdder() {
         return Optional.empty();
     }