Enhance nullability annotations and documentation in LocalizedText (#6149)

Author: Glavo

HMCLCore/src/main/java/org/jackhuang/hmcl/util/i18n/LocalizedText.java

@@ -23,28 +23,60 @@
 import com.google.gson.stream.JsonReader;
 import com.google.gson.stream.JsonToken;
 import com.google.gson.stream.JsonWriter;
-import org.jetbrains.annotations.NotNull;
+import org.jackhuang.hmcl.util.gson.JsonSerializable;
+import org.jetbrains.annotations.NotNullByDefault;
 import org.jetbrains.annotations.Nullable;
 
 import java.io.IOException;
 import java.util.*;
 
+/// Represents text that may either be locale-independent or stored as values keyed by language tags.
+///
+/// The JSON representation accepts either a string or an object. A string is treated as the same text for every
+/// locale, while an object maps language keys, such as `en`, `zh-Hans`, or `default`, to localized text values.
+///
+/// @author Glavo
+@NotNullByDefault
 @JsonAdapter(LocalizedText.Adapter.class)
+@JsonSerializable
 public final class LocalizedText {
+    /// Locale-independent text used when this instance is not backed by localized values.
     private final @Nullable String value;
+
+    /// Text values keyed by language keys generated by [LocaleUtils#toLanguageKey(Locale)].
     private final @Nullable Map<String, String> localizedValues;
 
-    public LocalizedText(String value) {
+    /// Creates a locale-independent text value.
+    ///
+    /// When `value` is `null`, [#getText(List)] returns `null` for every candidate locale.
+    ///
+    /// @param value the text value, or `null` if the text is absent
+    public LocalizedText(@Nullable String value) {
         this.value = value;
         this.localizedValues = null;
     }
 
-    public LocalizedText(@NotNull Map<String, String> localizedValues) {
+    /// Creates a localized text value backed by language-key mappings.
+    ///
+    /// The map is stored directly and is not copied. Later changes to `localizedValues` are visible through this
+    /// instance.
+    ///
+    /// @param localizedValues text values keyed by language keys generated by [LocaleUtils#toLanguageKey(Locale)]
+    /// @throws NullPointerException if `localizedValues` is `null`
+    public LocalizedText(Map<String, String> localizedValues) {
         this.value = null;
         this.localizedValues = Objects.requireNonNull(localizedValues);
     }
 
-    public String getText(@NotNull List<Locale> candidates) {
+    /// Returns the best matching text for the given candidate locales.
+    ///
+    /// If this instance stores localized values, the candidates are checked in iteration order after conversion with
+    /// [LocaleUtils#toLanguageKey(Locale)]. The first matching value is returned, or `null` if no candidate matches.
+    /// If this instance stores locale-independent text, the stored value is returned without checking `candidates`.
+    ///
+    /// @param candidates candidate locales ordered from most preferred to least preferred
+    /// @return the matched text, the locale-independent text, or `null` if no text is available
+    public @Nullable String getText(List<Locale> candidates) {
         if (localizedValues != null) {
             for (Locale locale : candidates) {
                 String value = localizedValues.get(LocaleUtils.toLanguageKey(locale));
@@ -56,10 +88,17 @@ public String getText(@NotNull List<Locale> candidates) {
             return value;
     }
 
+    /// Gson adapter for the compact localized text JSON representation.
     static final class Adapter extends TypeAdapter<LocalizedText> {
 
+        /// Reads a localized text value from `null`, a JSON string, or a JSON object.
+        ///
+        /// @param jsonReader the reader positioned at the next localized text value
+        /// @return the parsed localized text, or `null` if the next JSON token is `null`
+        /// @throws IOException if reading from `jsonReader` fails
+        /// @throws JsonSyntaxException if the next token is neither `null`, a string, nor an object
         @Override
-        public LocalizedText read(JsonReader jsonReader) throws IOException {
+        public @Nullable LocalizedText read(JsonReader jsonReader) throws IOException {
             JsonToken nextToken = jsonReader.peek();
             if (nextToken == JsonToken.NULL) {
                 return null;
@@ -83,8 +122,13 @@ public LocalizedText read(JsonReader jsonReader) throws IOException {
             }
         }
 
+        /// Writes a localized text value as `null`, a JSON string, or a JSON object.
+        ///
+        /// @param jsonWriter the writer that receives the JSON representation
+        /// @param localizedText the localized text to write, or `null` to write a JSON `null`
+        /// @throws IOException if writing to `jsonWriter` fails
         @Override
-        public void write(JsonWriter jsonWriter, LocalizedText localizedText) throws IOException {
+        public void write(JsonWriter jsonWriter, @Nullable LocalizedText localizedText) throws IOException {
             if (localizedText == null) {
                 jsonWriter.nullValue();
             } else if (localizedText.localizedValues != null) {