Better AddonLifecycle AddonEvent docs (#1964)

Co-authored-by: Kaz Wolfe <root@kazwolfe.io>
Co-authored-by: Haselnussbomber <mail@haselnussbomber.de>

Dalamud/Game/Addon/Lifecycle/AddonEvent.cs

@@ -1,4 +1,8 @@
-namespace Dalamud.Game.Addon.Lifecycle;
+using Dalamud.Game.Addon.Lifecycle.AddonArgTypes;
+
+using FFXIVClientStructs.FFXIV.Component.GUI;
+
+namespace Dalamud.Game.Addon.Lifecycle;
 
 /// <summary>
 /// Enumeration for available AddonLifecycle events.
@@ -6,67 +10,112 @@
 public enum AddonEvent
 {
     /// <summary>
-    /// Event that is fired before an addon begins it's setup process.
+    /// An event that is fired prior to an addon being setup with its implementation of
+    /// <see cref="AtkUnitBase.OnSetup"/>. This event is useful for modifying the initial data contained within
+    /// <see cref="AddonSetupArgs.AtkValueSpan"/> prior to the addon being created.
     /// </summary>
+    /// <seealso cref="AddonSetupArgs"/>
     PreSetup,
-
+    
     /// <summary>
-    /// Event that is fired after an addon has completed it's setup process.
+    /// An event that is fired after an addon has finished its initial setup. This event is particularly useful for
+    /// developers seeking to add custom elements to now-initialized and populated node lists, as well as reading data
+    /// placed in the AtkValues by the game during the setup process.
+    /// See <see cref="PreSetup"/> for more information.
     /// </summary>
     PostSetup,
 
     /// <summary>
-    /// Event that is fired before an addon begins update.
+    /// An event that is fired before an addon begins its update cycle via <see cref="AtkUnitBase.Update"/>. This event
+    /// is fired every frame that an addon is loaded, regardless of visibility.
     /// </summary>
+    /// <seealso cref="AddonUpdateArgs"/>
     PreUpdate,
 
     /// <summary>
-    /// Event that is fired after an addon has completed update.
+    /// An event that is fired after an addon has finished its update.
+    /// See <see cref="PreUpdate"/> for more information.
     /// </summary>
     PostUpdate,
 
     /// <summary>
-    /// Event that is fired before an addon begins draw.
+    /// An event that is fired before an addon begins drawing to screen via <see cref="AtkUnitBase.Draw"/>. Unlike
+    /// <see cref="PreUpdate"/>, this event is only fired if an addon is visible or otherwise drawing to screen.
     /// </summary>
+    /// <seealso cref="AddonDrawArgs"/>
     PreDraw,
 
     /// <summary>
-    /// Event that is fired after an addon has completed draw.
+    /// An event that is fired after an addon has finished its draw to screen.
+    /// See <see cref="PreDraw"/> for more information.
     /// </summary>
     PostDraw,
 
     /// <summary>
-    /// Event that is fired before an addon is finalized.
+    /// An event that is fired immediately before an addon is finalized via <see cref="AtkUnitBase.Finalize"/> and
+    /// destroyed. After this event, the addon will destruct its UI node data as well as free any allocated memory.
+    /// This event can be used for cleanup and tracking tasks.
     /// </summary>
+    /// <remarks>
+    /// This event is <em>NOT</em> fired when the addon is being hidden, but tends to be fired when it's being properly
+    /// closed.
+    /// <br />
+    /// As this is part of the destruction process for an addon, this event does not have an associated Post event.
+    /// </remarks>
+    /// <seealso cref="AddonFinalizeArgs"/>
     PreFinalize,
     
     /// <summary>
-    /// Event that is fired before an addon begins a requested update.
+    /// An event that is fired before a call to <see cref="AtkUnitBase.OnRequestedUpdate"/> is made in response to a
+    /// change in the subscribed <see cref="AddonRequestedUpdateArgs.NumberArrayData"/> or
+    /// <see cref="AddonRequestedUpdateArgs.StringArrayData"/> backing this addon. This generally occurs in response to
+    /// receiving data from the game server, but can happen in other cases as well. This event is useful for modifying
+    /// the data received before it's passed to the UI for display. Contrast to <see cref="PreRefresh"/> which tends to
+    /// be in response to <em>client-driven</em> interactions.
     /// </summary>
+    /// <seealso cref="AddonRequestedUpdateArgs"/>
+    /// <seealso cref="PostRequestedUpdate"/>
+    /// <example>
+    /// A developer would use this event to intercept free company information after it's received from the server, but
+    /// before it's displayed to the user. This would allow the developer to add user-driven notes or other information
+    /// to the Free Company's overview.
+    /// </example>
     PreRequestedUpdate,
     
     /// <summary>
-    /// Event that is fired after an addon finishes a requested update.
+    /// An event that is fired after an addon has finished processing an <c>ArrayData</c> update.
+    /// See <see cref="PreRequestedUpdate"/> for more information.
     /// </summary>
     PostRequestedUpdate,
     
     /// <summary>
-    /// Event that is fired before an addon begins a refresh.
+    /// An event that is fired before an addon calls its <see cref="AtkUnitManager.RefreshAddon"/> method. Refreshes are
-    /// </summary>
+    /// generally triggered in response to certain user interactions such as changing tabs, and are primarily used to
+    /// update the <c>AtkValue</c>s present in this addon. Contrast to <see cref="PreRequestedUpdate"/> which is called
+    /// in response to <c>ArrayData</c> updates.</summary>
+    /// <seealso cref="AddonRefreshArgs"/>
+    /// <seealso cref="PostRefresh"/>
     PreRefresh,
     
     /// <summary>
-    /// Event that is fired after an addon has finished a refresh.
+    /// An event that is fired after an addon has finished its refresh.
+    /// See <see cref="PreRefresh"/> for more information.
     /// </summary>
     PostRefresh,
     
     /// <summary>
-    /// Event that is fired before an addon begins processing an event.
+    /// An event that is fired before an addon begins processing a user-driven event via
+    /// <see cref="AtkEventListener.ReceiveEvent"/>, such as mousing over an element or clicking a button. This event
+    /// is only valid for addons that actually override the <c>ReceiveEvent</c> method of the underlying
+    /// AtkEventListener.
     /// </summary>
+    /// <seealso cref="AddonReceiveEventArgs"/>
+    /// <seealso cref="PostReceiveEvent"/>
     PreReceiveEvent,
     
     /// <summary>
-    /// Event that is fired after an addon has processed an event.
+    /// An event that is fired after an addon finishes calling its <see cref="AtkEventListener.ReceiveEvent"/> method.
+    /// See <see cref="PreReceiveEvent"/> for more information.
     /// </summary>
     PostReceiveEvent,
 }