add party javadoc

Hexaoxide · Sep 30, 2023 · d45f3e8 · d45f3e8
1 parent cd14215
commit d45f3e8
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 0 deletions.
diff --git a/api/src/main/java/net/draycia/carbon/api/users/CarbonPlayer.java b/api/src/main/java/net/draycia/carbon/api/users/CarbonPlayer.java
@@ -405,6 +405,12 @@ record ChannelMessage(Component message, ChatChannel channel) {}
      */
     void leaveChannel(ChatChannel channel);
 
+    /**
+     * Get this player's current {@link Party}.
+     *
+     * @return party future
+     * @since 2.1.0
+     */
     CompletableFuture<@Nullable Party> party();
 
 }
diff --git a/api/src/main/java/net/draycia/carbon/api/users/Party.java b/api/src/main/java/net/draycia/carbon/api/users/Party.java
@@ -25,17 +25,61 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.framework.qual.DefaultQualifier;
 
+/**
+ * Reference to a chat party.
+ *
+ * @see UserManager#createParty(Component)
+ * @see UserManager#party(UUID)
+ * @since 2.1.0
+ */
 @DefaultQualifier(NonNull.class)
 public interface Party {
+
+    /**
+     * Get the name of this party.
+     *
+     * @return party name
+     * @since 2.1.0
+     */
     Component name();
 
+    /**
+     * Get the unique id of this party.
+     *
+     * @return party id
+     * @since 2.1.0
+     */
     UUID id();
 
+    /**
+     * Get a snapshot of the current party members.
+     *
+     * @return party members
+     * @since 2.1.0
+     */
     Set<UUID> members();
 
+    /**
+     * Add a user to this party. They will automatically be removed from their previous party if necessary.
+     *
+     * @param id user id
+     * @since 2.1.0
+     */
     void addMember(UUID id);
 
+    /**
+     * Remove a user from this party.
+     *
+     * @param id user id
+     * @since 2.1.0
+     */
     void removeMember(UUID id);
 
+    /**
+     * Disband this party. Will remove all members and delete persistent data.
+     *
+     * @since 2.1.0
+     */
     void disband();
+
 }
diff --git a/api/src/main/java/net/draycia/carbon/api/users/UserManager.java b/api/src/main/java/net/draycia/carbon/api/users/UserManager.java
@@ -47,8 +47,29 @@ public interface UserManager<C extends CarbonPlayer> {
      */
     CompletableFuture<C> user(UUID uuid);
 
+    /**
+     * Create a new {@link Party} with the specified name.
+     *
+     * <p>Parties with no users will not be saved. Use {@link Party#disband()} to discard.</p>
+     * <p>The returned reference will expire after one minute, store {@link Party#id()} rather than the instance and use {@link #party(UUID)} to retrieve.</p>
+     *
+     * @param name party name
+     * @return new party
+     * @since 2.1.0
+     */
     Party createParty(Component name);
 
+    /**
+     * Look up an existing party by its id.
+     *
+     * <p>As parties that have never had a user are not saved, they are not retrievable here.</p>
+     * <p>The returned reference will expire after one minute, do not cache it. The implementation handles caching as is appropriate.</p>
+     *
+     * @param id party id
+     * @return existing party
+     * @see #createParty(Component)
+     * @since 2.1.0
+     */
     CompletableFuture<@Nullable Party> party(UUID id);
 
 }