Документирование и небольшой рефакторинг модели.

2025-05-11 00:31:15 +04:00
parent 1a977ee988
commit 3c65274b45
64 changed files with 1960 additions and 554 deletions
@@ -3,8 +3,16 @@ using System.Reflection;

 namespace Pf2eModel.Model.Common.I18n;

+/// <summary>
+/// Расширения для работы с локализацией.
+/// </summary>
 public static class LocaleExtension
 {
+    /// <summary>
+    /// Получение строкового представления типа локализации.
+    /// </summary>
+    /// <param name="localeType">Тип локализации.</param>
+    /// <returns>Строковое представление типа локализации.</returns>
    public static string GetTypeString(this LocaleType localeType)
    {
        FieldInfo fi = localeType.GetType().GetField(localeType.ToString())!;
@@ -16,7 +24,13 @@ public static class LocaleExtension
            ?? localeType.ToString();
    }

-    public static LocaleType GetTypeByString(this string localeType)
+    /// <summary>
+    /// Получение типа локализации по строковому представлению типа локализации.
+    /// </summary>
+    /// <param name="localeTypeString">Строковое представление типа локализации.</param>
+    /// <returns>Тип локализации.</returns>
+    /// <exception cref="InvalidEnumArgumentException">Исключение, если строковое представление не соответсвует ни одному типу локализации.</exception>
+    public static LocaleType GetTypeByString(this string localeTypeString)
    {
        foreach (FieldInfo field in typeof(LocaleType).GetFields())
        {
@@ -28,7 +42,7 @@ public static class LocaleExtension
                continue;
            }

-            if (descriptionAttribute.Description == localeType)
+            if (descriptionAttribute.Description == localeTypeString)
            {
                return (LocaleType)field.GetValue(null)!;
            }
@@ -36,6 +50,7 @@ public static class LocaleExtension

        throw new InvalidEnumArgumentException();
    }
+
    /*
    public static IQueryable<T> WhereLocale(
        this IQueryable<T> query, Expression<Func<T, LocaleString>> expression, string searchTerm) where T : class
@@ -1,11 +1,26 @@
 namespace Pf2eModel.Model.Common.I18n;

+/// <summary>
+/// Элемент локализации.
+/// </summary>
+/// <param name="type">Тип локализации.</param>
+/// <param name="value">Значение локализации.</param>
 public class LocaleItem(LocaleType type, string value)
 {
+    /// <summary>
+    /// Тип локализации.
+    /// </summary>
    public LocaleType Locale { get; set; } = type;

+    /// <summary>
+    /// Значение локализации.
+    /// </summary>
    public string Value { get; set; } = value;

+    /// <summary>
+    /// Конструктор класса <see cref="LocaleItem"/> по паре ключ-значение.
+    /// </summary>
+    /// <param name="item">Пара ключ-значение по строковому представлению типа.</param>
    public LocaleItem(KeyValuePair<string, string> item)
-        : this(LocaleExtension.GetTypeByString(item.Key), item.Value) { }
+        : this(item.Key.GetTypeByString(), item.Value) { }
 }
@@ -3,40 +3,90 @@ using Newtonsoft.Json.Linq;

 namespace Pf2eModel.Model.Common.I18n;

+/// <summary>
+/// Локализованная строка.
+/// </summary>
 public class LocaleString : ICollection<LocaleItem>
 {
+    /// <summary>
+    /// Список локализаций строк.
+    /// </summary>
    private readonly List<LocaleItem> _items = [];

+    /// <summary>
+    /// Проверяет наличие хотя бы одной локализации.
+    /// </summary>
    private void AssureDefault()
    {
        if (_items.Count == 0)
        {
-            _items.Add(new LocaleItem(LocaleType.English, string.Empty));
+            _items.Add(new(LocaleType.English, string.Empty));
        }
    }

+    /// <summary>
+    /// Количество локализаций.
+    /// </summary>
    public int Count => _items.Count;

-    public bool IsReadOnly => false;
-
+    /// <summary>
+    /// Коллекция реализованных типов локализаций.
+    /// </summary>
    public ICollection<LocaleType> Types => _items.Select(c => c.Locale).ToList();

+    /// <inheritdoc/>
+    public bool IsReadOnly => false;
+
+    /// <summary>
+    /// Конструктор класса <see cref="LocaleString"/>.
+    /// </summary>
    public LocaleString()
    {
        AssureDefault();
    }

-    private LocaleType _E(string localeString) => LocaleExtension.GetTypeByString(localeString);
+    /// <summary>
+    /// Получение типа локализации по строковому представлению.
+    /// </summary>
+    /// <param name="localeString">Строковое представление.</param>
+    /// <returns>Тип локализации.</returns>
+    private LocaleType _E(string localeString) => localeString.GetTypeByString();

+    /// <summary>
+    /// Получение типа локализации с учётом её наличия в коллекции.
+    /// </summary>
+    /// <param name="locale">Искомый тип локализации.</param>
+    /// <returns>Реальный тип локализации.</returns>
    private LocaleType RealLocale(LocaleType locale) =>
        Contains(locale) ? locale : LocaleType.English;

+    /// <summary>
+    /// Получение типа локализации по строковому представлению с учётом её наличия в коллекции.
+    /// </summary>
+    /// <param name="localeString">Строковое представление искомого типа локализации.</param>
+    /// <returns>Реальный тип локализации.</returns>
    private LocaleType RealLocale(string localeString) => RealLocale(_E(localeString));

+    /// <summary>
+    /// Получение объекта локализованной строки по типу локализации.
+    /// </summary>
+    /// <param name="locale">Искомый тип локализации.</param>
+    /// <returns>Объект локализованной строки.</returns>
    public LocaleItem GetItem(LocaleType locale) => this.First(c => c.Locale == RealLocale(locale));

-    public LocaleItem GetItem(string locale) => this.First(c => c.Locale == RealLocale(locale));
+    /// <summary>
+    /// Получение объекта локализованной строки по строковому представлению типа локализации.
+    /// </summary>
+    /// <param name="localeString">Строковое представление искомого типа локализации.</param>
+    /// <returns>Объект локализованной строки.</returns>
+    public LocaleItem GetItem(string localeString) =>
+        this.First(c => c.Locale == RealLocale(localeString));

+    /// <summary>
+    /// Получение локализованной строки по типу локализации.
+    /// </summary>
+    /// <param name="locale">Искомый тип локализации.</param>
+    /// <returns>Локализованная строка.</returns>
    public string this[LocaleType locale]
    {
        get => GetItem(locale).Value;
@@ -48,52 +98,87 @@ public class LocaleString : ICollection<LocaleItem>
            }
            else
            {
-                _items.Add(new LocaleItem(locale, value));
+                _items.Add(new(locale, value));
            }
        }
    }
+
+    /// <summary>
+    /// Получение локализованной строки по типу локализации.
+    /// </summary>
+    /// <param name="localeString">Строковое представление искомого типа локализации.</param>
+    /// <returns>Локализованная строка.</returns>
    public string this[string localeString]
    {
        get => this[_E(localeString)];
        set => this[_E(localeString)] = value;
    }

+    /// <summary>
+    /// Добавление объекта локализованной строки в коллекцию.
+    /// </summary>
+    /// <param name="item">Объект локализированной строки.</param>
    public void Add(LocaleItem item)
    {
        this[item.Locale] = item.Value;
    }

+    /// <summary>
+    /// Добавление локализованной строки в коллекцию.
+    /// </summary>
+    /// <param name="locale">Тип локализации.</param>
+    /// <param name="value">Строка локазации.</param>
    public void Add(LocaleType locale, string value)
    {
        this[locale] = value;
    }

+    /// <summary>
+    /// Отчистка коллекции локализованных строк.
+    /// </summary>
    public void Clear()
    {
        _items.Clear();
        AssureDefault();
    }

+    /// <summary>
+    /// Проверка наличия объекта локализованной строки в коллекции.
+    /// </summary>
+    /// <param name="item">Объект локализированной строки.</param>
+    /// <returns>`true`, если объект есть; `false`, если нет.</returns>
    public bool Contains(LocaleItem item)
    {
        return _items.Contains(item);
    }

+    /// <summary>
+    /// Проверка наличия локализованной строки в коллекции по типу локализации.
+    /// </summary>
+    /// <param name="locale">Тип локализации.</param>
+    /// <returns>`true`, если искомый тип локализации есть; `false`, если нет.</returns>
    public bool Contains(LocaleType locale)
    {
        return Types.Contains(locale);
    }

-    public bool Contains(string value)
+    /// <summary>
+    /// Проверка наличия локализованной строки в коллекции по строковому представлению типа локализации.
+    /// </summary>
+    /// <param name="localeString">Строковое представление искомого типа локализации.</param>
+    /// <returns>`true`, если искомый тип локализации есть; `false`, если нет.</returns>
+    public bool Contains(string localeString)
    {
-        return this.Any(item => item.Value == value);
+        return this.Any(item => item.Value == localeString);
    }

+    /// <inheritdoc/>
    public void CopyTo(LocaleItem[] array, int arrayIndex)
    {
        throw new NotImplementedException();
    }

+    /// <inheritdoc/>
    public bool Remove(LocaleItem item)
    {
        bool result = _items.Remove(item);
@@ -107,21 +192,28 @@ public class LocaleString : ICollection<LocaleItem>
        return result;
    }

+    /// <inheritdoc/>
    public IEnumerator<LocaleItem> GetEnumerator()
    {
        return _items.GetEnumerator();
    }

+    /// <inheritdoc/>
    IEnumerator IEnumerable.GetEnumerator()
    {
        return GetEnumerator();
    }

+    /// <inheritdoc/>
    public override string ToString()
    {
        return this[LocaleType.English];
    }

+    /// <summary>
+    /// Сериализация локализованной строки в JSON-формат.
+    /// </summary>
+    /// <returns>Строковое представление JSON-представления.</returns>
    public string Serialize()
    {
        JObject json = [];
@@ -134,10 +226,15 @@ public class LocaleString : ICollection<LocaleItem>
        return json.ToString();
    }

+    /// <summary>
+    /// Десериализация локализованной строки из JSON-формата.
+    /// </summary>
+    /// <param name="input">Строковое представление JSON-представления.</param>
+    /// <returns>Объект локализованной строки.</returns>
    public static LocaleString Deserialize(string input)
    {
        JObject json = JObject.Parse(input);
-        LocaleString result = new();
+        LocaleString result = [];

        foreach (KeyValuePair<string, JToken?> item in json)
        {
@@ -2,6 +2,9 @@

 namespace Pf2eModel.Model.Common.I18n;

+/// <summary>
+/// Тип локализации.
+/// </summary>
 public enum LocaleType
 {
    [Description("en")]