docs: добавлена полная документация и ревизия TeX модуля

Author: Infarh

MathCore.WPF/TeX/Atom.cs

@@ -1,19 +1,56 @@
 namespace MathCore.WPF.TeX;
 
-/// <summary>Atom (smallest unit) of TexFormula</summary>
+/// <summary>
+/// Атом (наименьшая единица) TeX формулы
+/// </summary>
+/// <remarks>
+/// Атомы - это строительные блоки всех математических формул в TeX модуле.
+/// Каждый атом отвечает за:
+/// 1. Хранение своих данных (символы, подформулы и т.д.)
+/// 2. Определение своего типа (Ordinary, BinaryOperator, Relation и т.д.)
+/// 3. Преобразование себя в визуальный бокс для рендеринга
+/// 
+/// Существуют различные типы атомов: CharAtom (символ), RowAtom (ряд атомов),
+/// FractionAtom (дробь), ScriptsAtom (индексы) и другие.
+/// </remarks>
 internal abstract class Atom
 {
+    /// <summary>Инициализирует новый экземпляр атома со стандартным типом Ordinary</summary>
     protected Atom() => Type = TexAtomType.Ordinary;
 
+    /// <summary>
+    /// Тип атома, определяющий его математические свойства и расстояния до соседних элементов
+    /// </summary>
     public TexAtomType Type { get; set; }
 
+    /// <summary>
+    /// Преобразует атом в визуальный бокс для рендеринга в указанной среде
+    /// </summary>
+    /// <param name="environment">Среда рендеринга с информацией о стиле, шрифте и других параметрах</param>
+    /// <returns>Бокс, который содержит визуальное представление этого атома</returns>
+    /// <remarks>
+    /// Каждый подкласс Atom реализует этот метод для преобразования своих данных
+    /// в визуальное представление. Рекурсивно вызывается для всех дочерних атомов.
+    /// </remarks>
     public abstract Box CreateBox(TexEnvironment environment);
 
-    /// <summary>Gets type of leftmost child item</summary>
-    /// <returns></returns>
+    /// <summary>
+    /// Получает тип самого левого дочернего элемента (для подсчёта расстояний)
+    /// </summary>
+    /// <returns>Тип TexAtomType самого левого элемента</returns>
+    /// <remarks>
+    /// Используется при подсчёте расстояний между соседними атомами.
+    /// Для составных атомов (RowAtom, FractionAtom) возвращает тип левого потомка.
+    /// </remarks>
     public virtual TexAtomType GetLeftType() => Type;
 
-    /// <summary>Gets type of leftmost child item</summary>
-    /// <returns></returns>
+    /// <summary>
+    /// Получает тип самого правого дочернего элемента (для подсчёта расстояний)
+    /// </summary>
+    /// <returns>Тип TexAtomType самого правого элемента</returns>
+    /// <remarks>
+    /// Используется при подсчёте расстояний между соседними атомами.
+    /// Для составных атомов (RowAtom, FractionAtom) возвращает тип правого потомка.
+    /// </remarks>
     public virtual TexAtomType GetRightType() => Type;
 }

MathCore.WPF/TeX/Box.cs

@@ -2,34 +2,66 @@
 using System.Windows;
 using System.Windows.Media;
 
-// Represents graphical box that is part of math expression, and can itself contain child boxes.
 namespace MathCore.WPF.TeX;
 
+/// <summary>
+/// Визуальный бокс - графический элемент математического выражения, который может содержать дочерние боксы
+/// </summary>
+/// <remarks>
+/// Боксы - это результат преобразования атомов (Atom) в визуальное представление.
+/// Каждый бокс содержит:
+/// - Размеры (ширину, высоту, глубину)
+/// - Визуальные свойства (кисти для переднего плана и фона)
+/// - Дочерние боксы (для составных элементов)
+/// 
+/// Различные типы боксов отрисовывают себя по-разному:
+/// CharBox отрисовывает символ, HorizontalBox - ряд боксов, FractionBox - дробь и т.д.
+/// </remarks>
 public abstract class Box
 {
     private readonly List<Box> _Children;
     private readonly ReadOnlyCollection<Box> _ChildrenReadOnly;
 
+    /// <summary>Дочерние боксы, входящие в состав этого бокса</summary>
     public ReadOnlyCollection<Box> Children => _ChildrenReadOnly;
 
+    /// <summary>Кисть для отрисовки переднего плана (символы, линии и т.д.)</summary>
     public Brush? Foreground { get; set; }
 
+    /// <summary>Кисть для отрисовки фонового прямоугольника</summary>
     public Brush Background { get; set; }
 
+    /// <summary>
+    /// Общая высота бокса (высота над базовой линией + глубина ниже базовой линии)
+    /// </summary>
     public double TotalHeight => Height + Depth;
 
+    /// <summary>Ширина бокса (в единицах относительного размера, масштабируется при рендеринге)</summary>
     public double Width { get; set; }
 
+    /// <summary>Высота бокса выше базовой линии (в единицах относительного размера)</summary>
     public double Height { get; set; }
 
+    /// <summary>Глубина бокса ниже базовой линии (в единицах относительного размера)</summary>
     public double Depth { get; set; }
 
+    /// <summary>Вертикальное смещение бокса от базовой линии (положительное = вверх)</summary>
     public double Shift { get; set; }
 
+    /// <summary>
+    /// Инициализирует новый экземпляр бокса с использованием визуальных свойств из среды
+    /// </summary>
+    /// <param name="environment">Среда рендеринга с информацией о цветах и стилях</param>
     internal Box(TexEnvironment environment) : this(environment.Foreground, environment.Background) { }
 
+    /// <summary>Инициализирует новый экземпляр пустого бокса</summary>
     protected Box() : this(null, null) { }
 
+    /// <summary>
+    /// Инициализирует новый экземпляр бокса с заданными визуальными свойствами
+    /// </summary>
+    /// <param name="foreground">Кисть для переднего плана</param>
+    /// <param name="background">Кисть для фона</param>
     protected Box(Brush foreground, Brush background)
     {
         _Children         = [];
@@ -38,17 +70,43 @@ protected Box(Brush foreground, Brush background)
         Background       = background;
     }
 
+    /// <summary>
+    /// Отрисовывает бокс и его дочерние элементы в WPF DrawingContext
+    /// </summary>
+    /// <param name="Context">WPF контекст для отрисовки</param>
+    /// <param name="scale">Коэффициент масштабирования (обычно размер шрифта)</param>
+    /// <param name="x">Координата X в пиксельных точках</param>
+    /// <param name="y">Координата Y в пиксельных точках (базовая линия)</param>
+    /// <remarks>
+    /// Базовая реализация отрисовывает фоновый прямоугольник, если задана кисть для фона.
+    /// Подклассы переопределяют этот метод для отрисовки своего специфичного содержимого.
+    /// </remarks>
     public virtual void Draw(DrawingContext Context, double scale, double x, double y)
     {
         if(Background is null) return;
-        // Fill background of box with color.
+        // Отрисовать фон бокса прямоугольником
         Context.DrawRectangle(Background, null, new(x * scale, (y - Height) * scale,
             Width * scale, (Height + Depth) * scale));
     }
 
+    /// <summary>Добавляет дочерний бокс в конец списка дочерних элементов</summary>
+    /// <param name="box">Бокс для добавления</param>
     public virtual void Add(Box box) => _Children.Add(box);
 
+    /// <summary>
+    /// Вставляет дочерний бокс в указанную позицию в списке дочерних элементов
+    /// </summary>
+    /// <param name="position">Позиция для вставки (0-основана)</param>
+    /// <param name="box">Бокс для вставки</param>
     public virtual void Add(int position, Box box) => _Children.Insert(position, box);
 
+    /// <summary>
+    /// Получает идентификатор последнего используемого шрифта в этом боксе и его дочерних элементах
+    /// </summary>
+    /// <returns>Идентификатор шрифта</returns>
+    /// <remarks>
+    /// Используется для оптимизации - когда несколько элементов используют один шрифт,
+    /// можно избежать переключения контекста рендеринга.
+    /// </remarks>
     public abstract int GetLastFontId();
 }

MathCore.WPF/TeX/HorizontalBox.cs

@@ -2,11 +2,24 @@
 
 namespace MathCore.WPF.TeX;
 
-/// <summary>Box containing horizontal stack of child boxes</summary>
+/// <summary>
+/// Бокс, содержащий горизонтальный стек дочерних боксов
+/// </summary>
+/// <remarks>
+/// HorizontalBox используется для размещения боксов в горизонтальном направлении.
+/// Поддерживает выравнивание (влево, по центру, вправо).
+/// </remarks>
 internal sealed class HorizontalBox : Box
 {
+    /// <summary>Общая ширина всех дочерних боксов</summary>
     private double _ChildBoxesTotalWidth;
 
+    /// <summary>
+    /// Инициализирует новый бокс с одним элементом и заданным выравниванием
+    /// </summary>
+    /// <param name="box">Элемент для размещения</param>
+    /// <param name="width">Требуемая ширина контейнера</param>
+    /// <param name="alignment">Выравнивание (Center, Left, Right)</param>
     public HorizontalBox(Box box, double width, TexAlignment alignment)
         : this()
     {
@@ -30,12 +43,20 @@ public HorizontalBox(Box box, double width, TexAlignment alignment)
         }
     }
 
+    /// <summary>Инициализирует новый горизонтальный бокс с одним элементом</summary>
+    /// <param name="box">Элемент для добавления</param>
     public HorizontalBox(Box box) : this() => Add(box);
 
+    /// <summary>Инициализирует новый горизонтальный бокс с кистями для отрисовки</summary>
+    /// <param name="foreground">Кисть переднего плана</param>
+    /// <param name="background">Кисть фона</param>
     public HorizontalBox(Brush foreground, Brush background) : base(foreground, background) { }
 
+    /// <summary>Инициализирует новый пустой горизонтальный бокс</summary>
     public HorizontalBox() { }
 
+    /// <summary>Добавляет дочерний бокс и обновляет общую ширину</summary>
+    /// <param name="box">Бокс для добавления</param>
     public override void Add(Box box)
     {
         base.Add(box);