From c55e47ee4d30be0b0f7ceefae069e7aa605d1a33 Mon Sep 17 00:00:00 2001
From: Loskh <1020612624@qq.com>
Date: Mon, 22 Dec 2025 23:34:22 +0800
Subject: [PATCH] docs: expand documentation for FontNo with TTC index details

---
 Dalamud/DalamudAsset.cs                       |  3 ++-
 Dalamud/Interface/FontIdentifier/IFontSpec.cs | 20 ++++++++++++++++-
 .../FontIdentifier/SingleFontSpec.cs          |  4 +---
 .../ManagedFontAtlas/SafeFontConfig.cs        | 22 +++++++++++++++++--
 4 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/Dalamud/DalamudAsset.cs b/Dalamud/DalamudAsset.cs
index 0dbd4cef1..07f0c0f0a 100644
--- a/Dalamud/DalamudAsset.cs
+++ b/Dalamud/DalamudAsset.cs
@@ -130,7 +130,8 @@ public enum DalamudAsset
     [DalamudAsset(DalamudAssetPurpose.Font)]
     [DalamudAssetPath("UIRes", "NotoSansCJK-Medium.ttc")]
     NotoSansCJKMedium = 2000,
-    
+
+    /// <summary>
     /// <see cref="DalamudAssetPurpose.TextureFromPng"/>: Atlas containing badges.
     /// </summary>
     [DalamudAsset(DalamudAssetPurpose.TextureFromPng)]
diff --git a/Dalamud/Interface/FontIdentifier/IFontSpec.cs b/Dalamud/Interface/FontIdentifier/IFontSpec.cs
index 8c7b94a9c..535909b54 100644
--- a/Dalamud/Interface/FontIdentifier/IFontSpec.cs
+++ b/Dalamud/Interface/FontIdentifier/IFontSpec.cs
@@ -25,8 +25,26 @@ public interface IFontSpec
     float LineHeightPx { get; }
 
     /// <summary>
-    /// Gets the font no.
+    /// Gets or sets the font face index within a TrueType Collection (TTC) file.
     /// </summary>
+    /// <remarks>
+    /// This property only applies to <see cref="DalamudAsset.NotoSansCJKRegular"/> and
+    /// <see cref="DalamudAsset.NotoSansCJKMedium"/>, which are TTC fonts bundling
+    /// multiple language-specific CJK glyph sets (Japanese, Traditional Chinese,
+    /// Simplified Chinese, Korean) into a single file.
+    /// 
+    /// The index corresponds to the font face order in the TTC:
+    /// <list type="bullet">
+    ///   <item><description>0 = Japanese</description></item>
+    ///   <item><description>1 = Traditional Chinese</description></item>
+    ///   <item><description>2 = Simplified Chinese</description></item>
+    ///   <item><description>3 = Korean</description></item>
+    /// </list>
+    /// 
+    /// This value is ignored for all other <see cref="DalamudAsset"/> entries.
+    /// Only one glyph set can be active at a time. In most cases, you can omit this—
+    /// Dalamud automatically selects the appropriate face based on the UI language.
+    /// </remarks>
     int FontNo { get; }
 
     /// <summary>
diff --git a/Dalamud/Interface/FontIdentifier/SingleFontSpec.cs b/Dalamud/Interface/FontIdentifier/SingleFontSpec.cs
index 96b566dfe..986fa4db2 100644
--- a/Dalamud/Interface/FontIdentifier/SingleFontSpec.cs
+++ b/Dalamud/Interface/FontIdentifier/SingleFontSpec.cs
@@ -65,9 +65,7 @@ public record SingleFontSpec : IFontSpec
     [JsonProperty]
     public ushort[]? GlyphRanges { get; init; }
 
-    /// <summary>
-    /// Gets the font no.
-    /// </summary>
+    /// <inheritdoc/>
     [JsonProperty]
     public int FontNo { get; init; }
 
diff --git a/Dalamud/Interface/ManagedFontAtlas/SafeFontConfig.cs b/Dalamud/Interface/ManagedFontAtlas/SafeFontConfig.cs
index 484c3540b..61646af3f 100644
--- a/Dalamud/Interface/ManagedFontAtlas/SafeFontConfig.cs
+++ b/Dalamud/Interface/ManagedFontAtlas/SafeFontConfig.cs
@@ -1,4 +1,4 @@
-using System.Numerics;
+using System.Numerics;
 using System.Runtime.CompilerServices;
 using System.Text;
 
@@ -48,8 +48,26 @@ public struct SafeFontConfig
     }
 
     /// <summary>
-    /// Gets or sets the index of font within a TTF/OTF file.
+    /// Gets or sets the font face index within a TrueType Collection (TTC) file.
     /// </summary>
+    /// <remarks>
+    /// This property only applies to <see cref="DalamudAsset.NotoSansCJKRegular"/> and
+    /// <see cref="DalamudAsset.NotoSansCJKMedium"/>, which are TTC fonts bundling
+    /// multiple language-specific CJK glyph sets (Japanese, Traditional Chinese,
+    /// Simplified Chinese, Korean) into a single file.
+    /// 
+    /// The index corresponds to the font face order in the TTC:
+    /// <list type="bullet">
+    ///   <item><description>0 = Japanese</description></item>
+    ///   <item><description>1 = Traditional Chinese</description></item>
+    ///   <item><description>2 = Simplified Chinese</description></item>
+    ///   <item><description>3 = Korean</description></item>
+    /// </list>
+    /// 
+    /// This value is ignored for all other <see cref="DalamudAsset"/> entries.
+    /// Only one glyph set can be active at a time. In most cases, you can omit this—
+    /// Dalamud automatically selects the appropriate face based on the UI language.
+    /// </remarks>
     public int FontNo
     {
         get => this.Raw.FontNo;