From d45f3e8b3765b93db633b8ded519f59b08dcdb1e Mon Sep 17 00:00:00 2001
From: Jason Penilla <11360596+jpenilla@users.noreply.github.com>
Date: Sat, 30 Sep 2023 09:39:47 -0700
Subject: [PATCH] add party javadoc

---
 .../carbon/api/users/CarbonPlayer.java        |  6 +++
 .../net/draycia/carbon/api/users/Party.java   | 44 +++++++++++++++++++
 .../draycia/carbon/api/users/UserManager.java | 21 +++++++++
 3 files changed, 71 insertions(+)

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
index 829aaff53..a95329cc5 100644
--- 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
index 3faaf7b4c..5001c81e3 100644
--- 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
index ccfaa5ffa..3f089c6a7 100644
--- 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);
 
 }