From 7f34841eee3121f85631c8a18da40559ebed152c Mon Sep 17 00:00:00 2001
From: Anna <git@anna.lgbt>
Date: Sun, 11 Apr 2021 09:42:59 -0400
Subject: [PATCH] docs: document public api

---
 XivCommon/Functions/BattleTalk.cs  | 35 +++++++++++++++++++++++++++++-
 XivCommon/Functions/PartyFinder.cs |  9 ++++++++
 XivCommon/Hooks.cs                 | 17 +++++++++++++++
 3 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/XivCommon/Functions/BattleTalk.cs b/XivCommon/Functions/BattleTalk.cs
index f55b5a3..428533c 100755
--- a/XivCommon/Functions/BattleTalk.cs
+++ b/XivCommon/Functions/BattleTalk.cs
@@ -12,6 +12,9 @@ namespace XivCommon.Functions {
 
         public delegate void BattleTalkEventDelegate(ref SeString sender, ref SeString message, ref BattleTalkOptions options, ref bool isHandled);
 
+        /// <summary>
+        /// The event that is fired when a BattleTalk window is shown.
+        /// </summary>
         public event BattleTalkEventDelegate? OnBattleTalk;
 
         private delegate byte AddBattleTalkDelegate(IntPtr uiModule, IntPtr sender, IntPtr message, float duration, byte style);
@@ -67,6 +70,13 @@ namespace XivCommon.Functions {
             }
         }
 
+        /// <summary>
+        /// Show a BattleTalk window with the given options.
+        /// </summary>
+        /// <param name="sender">The name to attribute to the message</param>
+        /// <param name="message">The message to show in the window</param>
+        /// <param name="options">Optional options for the window</param>
+        /// <exception cref="InvalidOperationException">If the <see cref="Hooks.BattleTalk"/> hook is not enabled</exception>
         public void Show(SeString sender, SeString message, BattleTalkOptions? options = null) {
             this.Show(sender.Encode(), message.Encode(), options);
         }
@@ -98,17 +108,40 @@ namespace XivCommon.Functions {
 
     public class BattleTalkOptions {
         /// <summary>
-        /// Duration of the window in seconds.
+        /// Duration to display the window, in seconds.
         /// </summary>
         public float Duration { get; set; } = 5f;
 
+        /// <summary>
+        /// The style of the window.
+        /// </summary>
         public BattleTalkStyle Style { get; set; } = BattleTalkStyle.Normal;
     }
 
     public enum BattleTalkStyle : byte {
+        /// <summary>
+        /// A normal battle talk window with a white background.
+        /// </summary>
         Normal = 0,
+
+        /// <summary>
+        /// A battle talk window with a blue background and styled edges.
+        /// </summary>
         Aetherial = 6,
+
+        /// <summary>
+        /// A battle talk window styled similarly to a system text message (black background).
+        /// </summary>
         System = 7,
+
+        /// <summary>
+        /// <para>
+        /// A battle talk window with a blue, computer-y background.
+        /// </para>
+        /// <para>
+        /// Used by the Ultima Weapons (Ruby, Emerald, etc.).
+        /// </para>
+        /// </summary>
         Blue = 9,
     }
 }
diff --git a/XivCommon/Functions/PartyFinder.cs b/XivCommon/Functions/PartyFinder.cs
index 808d6c4..8a09316 100755
--- a/XivCommon/Functions/PartyFinder.cs
+++ b/XivCommon/Functions/PartyFinder.cs
@@ -37,6 +37,15 @@ namespace XivCommon.Functions {
             return this.RequestPfListingsHook!.Original(agent, categoryIdx);
         }
 
+        /// <summary>
+        /// <para>
+        /// Refresh the Party Finder listings. This does not open the Party Finder.
+        /// </para>
+        /// <para>
+        /// This maintains the currently selected category.
+        /// </para>
+        /// </summary>
+        /// <exception cref="InvalidOperationException">If the <see cref="Hooks.PartyFinder"/> hook is not enabled</exception>
         public void RefreshListings() {
             if (!this.Enabled) {
                 throw new InvalidOperationException("PartyFinder hooks are not enabled");
diff --git a/XivCommon/Hooks.cs b/XivCommon/Hooks.cs
index 6ebcfd4..7e165ba 100755
--- a/XivCommon/Hooks.cs
+++ b/XivCommon/Hooks.cs
@@ -3,8 +3,25 @@
 namespace XivCommon {
     [Flags]
     public enum Hooks {
+        /// <summary>
+        /// No hook.
+        ///
+        /// This flag is used to disable all hooking.
+        /// </summary>
         None,
+
+        /// <summary>
+        /// The BattleTalk hook.
+        ///
+        /// This hook is used in order to enable all BattleTalk functions.
+        /// </summary>
         BattleTalk,
+
+        /// <summary>
+        /// The Party Finder hooks.
+        ///
+        /// This hook is used in order to enable all Party Finder functions.
+        /// </summary>
         PartyFinder,
     }