Документация проекта отображения.

Pf2eViewer/EntityTreeViewer/StructureBuilder.cs

@@ -5,10 +5,23 @@ using Pf2eModel.Model.Common.I18n;
 
 namespace Pf2eViewer.EntityTreeViewer;
 
+/// <summary>
+/// Класс для построения структуры данных класса.
+/// </summary>
 internal class StructureBuilder
 {
+    /// <summary>
+    /// Список обработанных объектов.
+    /// </summary>
     private readonly List<StructureProcessedObject> _processedObjects = [];
 
+    /// <summary>
+    /// Создание поля структуры.
+    /// </summary>
+    /// <param name="name">Название поля.</param>
+    /// <param name="value">Значение поля.</param>
+    /// <param name="depth">Глубина, на котором поле отображается.</param>
+    /// <returns>Поле структуры.</returns>
     public StructureFieldComplex Create(string name, object value, int depth = 0)
     {
         _ = RegisterProcessed(value);
@@ -20,6 +33,11 @@ internal class StructureBuilder
         return field;
     }
 
+    /// <summary>
+    /// Регистрация обработанного объекта.
+    /// </summary>
+    /// <param name="value">Регистрируемый объект.</param>
+    /// <returns>`true`, если объект был добавлен; `false`, если объект был добавлен ранее.</returns>
     public bool RegisterProcessed(object value)
     {
         if (_processedObjects.Any(p => p.Value == value))
@@ -34,6 +52,11 @@ internal class StructureBuilder
         return true;
     }
 
+    /// <summary>
+    /// Дополнить обработанный объект.
+    /// </summary>
+    /// <param name="value">Значение.</param>
+    /// <param name="field">Поле объекта.</param>
     public void CompleteProcessed(object value, StructureFieldComplex field)
     {
         StructureProcessedObject? q = _processedObjects.FirstOrDefault(p => p.Value == value);
@@ -46,6 +69,13 @@ internal class StructureBuilder
         q.Field = field;
     }
 
+    /// <summary>
+    /// Выбор поля структуры по значению.
+    /// </summary>
+    /// <param name="name">Название поля.</param>
+    /// <param name="value">Значение поля.</param>
+    /// <param name="depth">Глубина, на котором поле отображается.</param>
+    /// <returns></returns>
     public StructureField Resolve(string name, object? value, int depth)
     {
         switch (GetFieldType(value))
@@ -87,6 +117,11 @@ internal class StructureBuilder
         throw new("Impossible");
     }
 
+    /// <summary>
+    /// Получить тип поля структуры по значению.
+    /// </summary>
+    /// <param name="value">Значение поля.</param>
+    /// <returns>Тип поля структуры.</returns>
     public static StructureFieldType GetFieldType(object? value)
     {
         if (value is null)
@@ -110,6 +145,10 @@ internal class StructureBuilder
     }
 }
 
+/// <summary>
+/// Класс для хранения обработанного объекта.
+/// </summary>
+/// <param name="value">Объект.</param>
 internal class StructureProcessedObject(object value)
 {
     public readonly object Value = value;
@@ -142,38 +181,109 @@ internal class StructureProcessedObject(object value)
     }
 }
 
+/// <summary>
+/// Тип поля структуры.
+/// </summary>
 internal enum StructureFieldType
 {
+    /// <summary>
+    /// Пустое поле.
+    /// </summary>
     Null,
+
+    /// <summary>
+    /// Простое поле.
+    /// </summary>
     Primitive,
+
+    /// <summary>
+    /// Поле с перечислением.
+    /// </summary>
     Enum,
+
+    /// <summary>
+    /// Поле с объектом.
+    /// </summary>
     Complex,
+
+    /// <summary>
+    /// Поле с ссылкой на объект.
+    /// </summary>
     Reference,
 }
 
+/// <summary>
+/// Тип лестницы глубины.
+/// </summary>
 internal enum LadderType
 {
+    /// <summary>
+    /// Пустой элемент: [ ].
+    /// </summary>
     Empty,
+
+    /// <summary>
+    /// Последний элемент: [└].
+    /// </summary>
     Last,
+
+    /// <summary>
+    /// Проходной элемент: [├] или [│].
+    /// </summary>
     Through,
 }
 
+/// <summary>
+/// Базовый класс для полей структуры.
+/// </summary>
+/// <param name="builder">Класс построения структуры данных.</param>
+/// <param name="name">Название поля.</param>
+/// <param name="depth">Глубина поля.</param>
 internal abstract class StructureField(StructureBuilder builder, string name, int depth)
 {
+    /// <summary>
+    /// Название поля.
+    /// </summary>
     public readonly string Name = name;
 
+    /// <summary>
+    /// Тип поля структуры.
+    /// </summary>
     public abstract StructureFieldType FieldType { get; }
 
+    /// <summary>
+    /// Класс построения структуры данных.
+    /// </summary>
     public readonly StructureBuilder Builder = builder;
 
+    /// <summary>
+    /// Флаг, указывающий, отображается ли поле.
+    /// </summary>
     public virtual bool Visible { get; set; } = true;
 
+    /// <summary>
+    /// Глубина поля структуры.
+    /// </summary>
     public readonly int Depth = depth;
 
+    /// <summary>
+    /// Получить строку, представляющую тип поля.
+    /// </summary>
+    /// <returns>Строка, представляющая тип поля.</returns>
     public abstract string GetTypeString();
 
+    /// <summary>
+    /// Получить строку, представляющую значение поля.
+    /// </summary>
+    /// <returns>Строка, представляющая значение поля.</returns>
     public abstract string GetValueString();
 
+    /// <summary>
+    /// Получить набор строк, используя результат функция.
+    /// </summary>
+    /// <typeparam name="T">Тип результирующей строки.</typeparam>
+    /// <param name="func">Функция, оборажения поля в результирующую строку.</param>
+    /// <returns>Коллекция, содержащая набор строк.</returns>
     public virtual ICollection<T> GetRows<T>(Func<StructureField, T> func)
     {
         StructureField[] q = [this];
@@ -181,16 +291,32 @@ internal abstract class StructureField(StructureBuilder builder, string name, in
     }
 }
 
+/// <summary>
+/// Пустое поле структуры.
+/// </summary>
+/// <param name="builder">Класс построения структуры данных.</param>
+/// <param name="name">Название поля.</param>
+/// <param name="depth">Глубина поля.</param>
 internal class StructureFieldNull(StructureBuilder builder, string name, int depth)
     : StructureField(builder, name, depth)
 {
+    /// <inheritdoc/>
     public override StructureFieldType FieldType => StructureFieldType.Null;
 
+    /// <inheritdoc/>
     public override string GetTypeString() => "null";
 
+    /// <inheritdoc/>
     public override string GetValueString() => "";
 }
 
+/// <summary>
+/// Простое поле структуры.
+/// </summary>
+/// <param name="builder">Класс построения структуры данных.</param>
+/// <param name="value">Значение поля.</param>
+/// <param name="name">Название поля.</param>
+/// <param name="depth">Глубина поля.</param>
 internal class StructureFieldPrimitive(
     StructureBuilder builder,
     object value,
@@ -198,12 +324,20 @@ internal class StructureFieldPrimitive(
     int depth
 ) : StructureField(builder, name, depth)
 {
+    /// <inheritdoc/>
     public override StructureFieldType FieldType => StructureFieldType.Primitive;
 
+    /// <summary>
+    /// Значение поля.
+    /// </summary>
     public readonly object Value = value;
 
+    /// <summary>
+    /// Тип значения поля.
+    /// </summary>
     public readonly Type Type = value.GetType();
 
+    /// <inheritdoc/>
     public override string GetTypeString()
     {
         return Type.GetTypeCode(Type) switch
@@ -216,6 +350,7 @@ internal class StructureFieldPrimitive(
         };
     }
 
+    /// <inheritdoc/>
     public override string GetValueString()
     {
         if (Type == typeof(string))
@@ -227,28 +362,57 @@ internal class StructureFieldPrimitive(
     }
 }
 
+/// <summary>
+/// Поле структуры с перечислением.
+/// </summary>
+/// <param name="builder">Класс построения структуры данных.</param>
+/// <param name="value">Значение поля.</param>
+/// <param name="name">Название поля.</param>
+/// <param name="depth">Глубина поля.</param>
 internal class StructureFieldEnum(StructureBuilder builder, object value, string name, int depth)
     : StructureField(builder, name, depth)
 {
+    /// <inheritdoc/>
     public override StructureFieldType FieldType => StructureFieldType.Enum;
 
+    /// <summary>
+    /// Значение поля.
+    /// </summary>
     public readonly object Value = value;
 
+    /// <summary>
+    /// Тип значения поля.
+    /// </summary>
     public readonly Type Type = value.GetType();
 
+    /// <inheritdoc/>
     public override string GetTypeString() => "enum";
 
+    /// <inheritdoc/>
     public override string GetValueString() => $"{Type.Name}.{Value}";
 }
 
+/// <summary>
+/// Поле стркутуры с объектом.
+/// </summary>
 internal class StructureFieldComplex : StructureField
 {
+    /// <inheritdoc/>
     public override StructureFieldType FieldType => StructureFieldType.Complex;
 
+    /// <summary>
+    /// Набор полей объекта.
+    /// </summary>
     public readonly List<StructureField> Fields = [];
 
+    /// <summary>
+    /// Тип значения поля.
+    /// </summary>
     public readonly Type Type;
 
+    /// <summary>
+    /// Флаг, указывающий, отображается ли поля объекта.
+    /// </summary>
     public bool Collapsed
     {
         get => _collapsed;
@@ -260,6 +424,7 @@ internal class StructureFieldComplex : StructureField
     }
     private bool _collapsed = false;
 
+    /// <inheritdoc/>
     public override bool Visible
     {
         get => _visible;
@@ -271,6 +436,13 @@ internal class StructureFieldComplex : StructureField
     }
     private bool _visible = true;
 
+    /// <summary>
+    /// Конструктор класса поля структуры с объектом.
+    /// </summary>
+    /// <param name="builder">Класс построения структуры данных.</param>
+    /// <param name="value">Значение поля.</param>
+    /// <param name="name">Название поля.</param>
+    /// <param name="depth">Глубина поля.</param>
     public StructureFieldComplex(StructureBuilder builder, object value, string name, int depth)
         : base(builder, name, depth)
     {
@@ -279,6 +451,9 @@ internal class StructureFieldComplex : StructureField
         SetFields((dynamic)value);
     }
 
+    /// <summary>
+    /// Обновить видимость полей структуры.
+    /// </summary>
     private void UpdateFieldVisibility()
     {
         foreach (StructureField field in Fields)
@@ -287,6 +462,10 @@ internal class StructureFieldComplex : StructureField
         }
     }
 
+    /// <summary>
+    /// Установить поля структуры `LocaleString`.
+    /// </summary>
+    /// <param name="localeString">Объект строки локализации.</param>
     private void SetFields(LocaleString localeString)
     {
         SetFieldsFromRecords(
@@ -296,6 +475,10 @@ internal class StructureFieldComplex : StructureField
         );
     }
 
+    /// <summary>
+    /// Установить поля структуры `IEnumerable`.
+    /// </summary>
+    /// <param name="enumerable">Объект-перечисление.</param>
     private void SetFields(IEnumerable enumerable)
     {
         int i = 0;
@@ -310,6 +493,10 @@ internal class StructureFieldComplex : StructureField
         SetFieldsFromRecords(records);
     }
 
+    /// <summary>
+    /// Установить поля структуры общего объекта.
+    /// </summary>
+    /// <param name="value">Объект.</param>
     private void SetFields(object value)
     {
         Type type = value.GetType();
@@ -325,6 +512,10 @@ internal class StructureFieldComplex : StructureField
         );
     }
 
+    /// <summary>
+    /// Установить поля структуры из списка записей.
+    /// </summary>
+    /// <param name="records"></param>
     private void SetFieldsFromRecords(List<FieldRecord> records)
     {
         foreach (
@@ -346,22 +537,35 @@ internal class StructureFieldComplex : StructureField
         }
     }
 
-    public override ICollection<T> GetRows<T>(Func<StructureField, T> func)
-    {
-        return [.. base.GetRows(func), .. Fields.SelectMany(f => f.GetRows(func)).ToList()];
-    }
-
+    /// <summary>
+    /// Запись поля структуры.
+    /// </summary>
+    /// <param name="name">Название поля.</param>
+    /// <param name="value">Значение поля.</param>
     private class FieldRecord(string name, object? value)
     {
+        /// <summary>
+        /// Название поля.
+        /// </summary>
         public readonly string Name = name;
 
+        /// <summary>
+        /// Значение поля.
+        /// </summary>
         public readonly object? Value = value;
 
+        /// <summary>
+        /// Тип поля структуры.
+        /// </summary>
         public StructureFieldType FieldType => StructureBuilder.GetFieldType(Value);
 
+        /// <summary>
+        /// Флаг, указывающий, использовать ли поле.
+        /// </summary>
         public bool Allowed = true;
     }
 
+    /// <inheritdoc/>
     public override string GetTypeString()
     {
         if (Type.IsGenericEnumerableType())
@@ -376,6 +580,7 @@ internal class StructureFieldComplex : StructureField
         }
     }
 
+    /// <inheritdoc/>
     public override string GetValueString()
     {
         if (Type.IsGenericEnumerableType())
@@ -384,8 +589,21 @@ internal class StructureFieldComplex : StructureField
         }
         return "";
     }
+
+    /// <inheritdoc/>
+    public override ICollection<T> GetRows<T>(Func<StructureField, T> func)
+    {
+        return [.. base.GetRows(func), .. Fields.SelectMany(f => f.GetRows(func)).ToList()];
+    }
 }
 
+/// <summary>
+/// Поле структуры с ссылкой на объект.
+/// </summary>
+/// <param name="builder">Класс построения структуры данных.</param>
+/// <param name="name">Название поля.</param>
+/// <param name="reference">Ссылка на объект.</param>
+/// <param name="depth">Глубина поля.</param>
 internal class StructureFieldReference(
     StructureBuilder builder,
     string name,
@@ -393,11 +611,17 @@ internal class StructureFieldReference(
     int depth
 ) : StructureField(builder, name, depth)
 {
+    /// <summary>
+    /// Ссылка на объект.
+    /// </summary>
     public StructureFieldComplex? Reference = reference;
 
+    /// <inheritdoc/>
     public override StructureFieldType FieldType => StructureFieldType.Reference;
 
+    /// <inheritdoc/>
     public override string GetTypeString() => Reference?.GetTypeString() ?? "???";
 
+    /// <inheritdoc/>
     public override string GetValueString() => "<Reference>";
 }