Document UI And Localization

UI/LocalizedText.cs

@@ -8,15 +8,25 @@ namespace ADOFAIRenderer.UI;
 /// <summary>
 /// Component that binds a TextMeshProUGUI component to a localization key or dynamic string provider,
 /// automatically updating the displayed text whenever the active language changes.
+/// <para>
+/// The text is set when the binding is made (<see cref="Bind(TextMeshProUGUI, string)"/>), when the component is enabled,
+/// and on every <see cref="LocalizationManager.OnLanguageChanged"/> event. A key and a dynamic provider are mutually
+/// exclusive: setting one clears the other. With neither set, <see cref="Refresh"/> leaves the text unchanged.
+/// Runs on the Unity main thread.
+/// </para>
 /// </summary>
 internal class LocalizedText : MonoBehaviour
 {
+    /// <summary>Text component that receives the string; looked up on the same GameObject if not assigned by Bind.</summary>
     private TextMeshProUGUI? _textComponent;
+    /// <summary>Localization key resolved through <see cref="LocalizationManager.Get(string)"/>; <c>null</c> when a provider is used.</summary>
     private string? _key;
+    /// <summary>Function that returns the full text (already localized/formatted); <c>null</c> when a key is used.</summary>
     private Func<string>? _dynamicProvider;
 
     /// <summary>
-    /// Gets or sets the localization key. Setting this will clear any dynamic provider.
+    /// Gets or sets the localization key. Setting this will clear any dynamic provider and refresh the text immediately.
+    /// A null or empty key leaves the current text as it is.
     /// </summary>
     public string? Key
     {
@@ -30,8 +40,11 @@ internal class LocalizedText : MonoBehaviour
     }
 
     /// <summary>
-    /// Sets a dynamic string provider function.
+    /// Sets a dynamic string provider function, clears the key and refreshes the text immediately.
+    /// The provider is called on every refresh (enable and language change), so it can combine several keys or
+    /// runtime values, e.g. a label that depends on UI state.
     /// </summary>
+    /// <param name="provider">Function returning the text to display; called on the Unity main thread.</param>
     public void SetDynamic(Func<string> provider)
     {
         _dynamicProvider = provider;
@@ -39,27 +52,35 @@ internal class LocalizedText : MonoBehaviour
         Refresh();
     }
 
+    /// <summary>
+    /// Finds the text component and subscribes to language changes. The subscription lasts until <see cref="OnDestroy"/>,
+    /// also while the component is disabled (a refresh of a disabled object only changes its text).
+    /// </summary>
     private void Awake()
     {
         EnsureComponent();
         LocalizationManager.OnLanguageChanged += HandleLanguageChanged;
     }
 
+    /// <summary>Refreshes the text each time the component is enabled.</summary>
     private void OnEnable()
     {
         Refresh();
     }
 
+    /// <summary>Unsubscribes from <see cref="LocalizationManager.OnLanguageChanged"/>.</summary>
     private void OnDestroy()
     {
         LocalizationManager.OnLanguageChanged -= HandleLanguageChanged;
     }
 
+    /// <summary>Language change handler; the new language is read by <see cref="LocalizationManager.Get(string)"/>.</summary>
     private void HandleLanguageChanged(SystemLanguage language)
     {
         Refresh();
     }
 
+    /// <summary>Assigns <see cref="_textComponent"/> from the same GameObject if it is not set yet.</summary>
     private void EnsureComponent()
     {
         if (_textComponent == null)
@@ -70,6 +91,8 @@ internal class LocalizedText : MonoBehaviour
 
     /// <summary>
     /// Refreshes the text using either the dynamic provider or the static localization key.
+    /// The provider takes precedence; with neither set, or without a text component, nothing changes.
+    /// A key that is missing in every locale is displayed as the key itself (see <see cref="LocalizationManager.Get(string)"/>).
     /// </summary>
     public void Refresh()
     {
@@ -88,7 +111,13 @@ internal class LocalizedText : MonoBehaviour
 
     /// <summary>
     /// Binds a TextMeshProUGUI component to a localization key.
+    /// Reuses the <see cref="LocalizedText"/> already on the target's GameObject or adds one, then sets the key,
+    /// which replaces any earlier binding and updates the text immediately.
     /// </summary>
+    /// <param name="target">Text to localize.</param>
+    /// <param name="key">Localization key, e.g. <c>"ui.render_config.codec"</c>.</param>
+    /// <returns>The binding component.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="target"/> is null.</exception>
     public static LocalizedText Bind(TextMeshProUGUI target, string key)
     {
         if (target == null) throw new ArgumentNullException(nameof(target));
@@ -100,7 +129,12 @@ internal class LocalizedText : MonoBehaviour
 
     /// <summary>
     /// Binds a TextMeshProUGUI component to a dynamic string provider function.
+    /// Reuses or adds the component like <see cref="Bind(TextMeshProUGUI, string)"/> and updates the text immediately.
     /// </summary>
+    /// <param name="target">Text to localize.</param>
+    /// <param name="provider">Function returning the text; called on every refresh.</param>
+    /// <returns>The binding component.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="target"/> is null.</exception>
     public static LocalizedText Bind(TextMeshProUGUI target, Func<string> provider)
     {
         if (target == null) throw new ArgumentNullException(nameof(target));