From 15034298a53e322a9b3299d454cfb296622d82a0 Mon Sep 17 00:00:00 2001
From: nebel <9887+nebel@users.noreply.github.com>
Date: Sun, 14 Jul 2024 19:42:57 +0900
Subject: [PATCH] Small improvements to NamePlateGui doc comments

---
 Dalamud/Game/Gui/NamePlate/NamePlateQuotedParts.cs   |  7 +++++++
 Dalamud/Game/Gui/NamePlate/NamePlateSimpleParts.cs   |  7 +++++++
 Dalamud/Game/Gui/NamePlate/NamePlateUpdateHandler.cs |  3 ++-
 Dalamud/Plugin/Services/INamePlateGui.cs             | 10 ++++++++--
 4 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/Dalamud/Game/Gui/NamePlate/NamePlateQuotedParts.cs b/Dalamud/Game/Gui/NamePlate/NamePlateQuotedParts.cs
index 40edee0fb..e05e553cd 100644
--- a/Dalamud/Game/Gui/NamePlate/NamePlateQuotedParts.cs
+++ b/Dalamud/Game/Gui/NamePlate/NamePlateQuotedParts.cs
@@ -6,6 +6,13 @@ namespace Dalamud.Game.Gui.NamePlate;
 /// A part builder for constructing and setting quoted nameplate fields (i.e. free company tag and title).
 /// </summary>
 /// <param name="field">The field type which should be set.</param>
+/// <remarks>
+/// This class works as a lazy writer initialized with empty parts, where an empty part signifies no change should be
+/// performed. Only after all handler processing is complete does it write out any parts which were set to the
+/// associated field. Reading fields from this class is usually not what you want to do, as you'll only be reading the
+/// contents of parts which other plugins have written to. Prefer reading from the base handler's properties or using
+/// <see cref="NamePlateInfoView"/>.
+/// </remarks>
 public class NamePlateQuotedParts(NamePlateStringField field, bool isFreeCompany)
 {
     /// <summary>
diff --git a/Dalamud/Game/Gui/NamePlate/NamePlateSimpleParts.cs b/Dalamud/Game/Gui/NamePlate/NamePlateSimpleParts.cs
index 444f0e390..2906005da 100644
--- a/Dalamud/Game/Gui/NamePlate/NamePlateSimpleParts.cs
+++ b/Dalamud/Game/Gui/NamePlate/NamePlateSimpleParts.cs
@@ -6,6 +6,13 @@ namespace Dalamud.Game.Gui.NamePlate;
 /// A part builder for constructing and setting a simple (unquoted) nameplate field.
 /// </summary>
 /// <param name="field">The field type which should be set.</param>
+/// <remarks>
+/// This class works as a lazy writer initialized with empty parts, where an empty part signifies no change should be
+/// performed. Only after all handler processing is complete does it write out any parts which were set to the
+/// associated field. Reading fields from this class is usually not what you want to do, as you'll only be reading the
+/// contents of parts which other plugins have written to. Prefer reading from the base handler's properties or using
+/// <see cref="NamePlateInfoView"/>.
+/// </remarks>
 public class NamePlateSimpleParts(NamePlateStringField field)
 {
     /// <summary>
diff --git a/Dalamud/Game/Gui/NamePlate/NamePlateUpdateHandler.cs b/Dalamud/Game/Gui/NamePlate/NamePlateUpdateHandler.cs
index d34aba904..565f04846 100644
--- a/Dalamud/Game/Gui/NamePlate/NamePlateUpdateHandler.cs
+++ b/Dalamud/Game/Gui/NamePlate/NamePlateUpdateHandler.cs
@@ -90,12 +90,13 @@ public interface INamePlateUpdateHandler
     /// <summary>
     /// Gets or sets the icon ID for the nameplate's marker icon, which is the large icon used to indicate quest
     /// availability and so on. This value is read from and reset by the game every frame, not just when a nameplate
-    /// changes.
+    /// changes. Setting this to 0 disables the icon.
     /// </summary>
     int MarkerIconId { get; set; }
 
     /// <summary>
     /// Gets or sets the icon ID for the nameplate's name icon, which is the small icon shown to the left of the name.
+    /// Setting this to -1 disables the icon.
     /// </summary>
     int NameIconId { get; set; }
 
diff --git a/Dalamud/Plugin/Services/INamePlateGui.cs b/Dalamud/Plugin/Services/INamePlateGui.cs
index 1f6c4ed6f..6fdc02bd3 100644
--- a/Dalamud/Plugin/Services/INamePlateGui.cs
+++ b/Dalamud/Plugin/Services/INamePlateGui.cs
@@ -21,13 +21,19 @@ public interface INamePlateGui
     /// An event which fires when nameplate data is updated and at least one nameplate has important updates. The
     /// subscriber is provided with a list of handlers for nameplates with important updates.
     /// </summary>
+    /// <remarks>
+    /// Fires after <see cref="OnDataUpdate"/>.
+    /// </remarks>
     event OnPlateUpdateDelegate? OnNamePlateUpdate;
 
     /// <summary>
     /// An event which fires when nameplate data is updated. The subscriber is provided with a list of handlers for all
-    /// nameplates. This event is likely to fire every frame even when no nameplates are actually updated, so in most
-    /// cases <see cref="OnNamePlateUpdate"/> is preferred.
+    /// nameplates.
     /// </summary>
+    /// <remarks>
+    /// This event is likely to fire every frame even when no nameplates are actually updated, so in most cases
+    /// <see cref="OnNamePlateUpdate"/> is preferred. Fires before <see cref="OnNamePlateUpdate"/>.
+    /// </remarks>
     event OnPlateUpdateDelegate? OnDataUpdate;
 
     /// <summary>