26.07.21

QWERTYkez.WordProcessor/ReplaceItem.cs

@@ -1,24 +1,71 @@
 namespace QWERTYkez.WordProcessor;
 
+/// <summary>
+/// Определяет тип разрыва или смены ориентации страницы,
+/// применяемый к элементу замены.
+/// </summary>
+public enum PageBreakType
+{
+    /// <summary>Без разрыва или смены ориентации.</summary>
+    None,
+
+    /// <summary>Обычный разрыв страницы (новый лист).</summary>
+    PageBreak,
+
+    /// <summary>Начать новую секцию с альбомной ориентацией страницы.</summary>
+    NewLandscapeSection,
+
+    /// <summary>Начать новую секцию с книжной ориентацией страницы.</summary>
+    NewPortraitSection,
+}
+
+/// <summary>
+/// Представляет элемент замены текста, содержащий сам текст и указание
+/// на тип разрыва или смены ориентации, который должен быть применён
+/// после вставки этого текста.
+/// </summary>
+/// <remarks>
+/// Используется в методах множественной замены, например,
+/// <see cref="IWordWriter.ReplaceItem(string, IEnumerable{ReplaceItem})"/>.
+/// </remarks>
 public readonly struct ReplaceItem
 {
+    /// <summary>
+    /// Инициализирует новый экземпляр <see cref="ReplaceItem"/> с пустым текстом
+    /// и типом разрыва <see cref="PageBreakType.None"/>.
+    /// </summary>
     public ReplaceItem() { }
-    public ReplaceItem(string text)
+
+    /// <summary>
+    /// Инициализирует новый экземпляр <see cref="ReplaceItem"/> с указанным текстом
+    /// и типом разрыва/смены ориентации.
+    /// </summary>
+    /// <param name="text">Текст, который будет вставлен вместо плейсхолдера.</param>
+    /// <param name="splitValue">
+    /// Тип разрыва или смены ориентации, который будет применён после вставки текста.
+    /// По умолчанию <see cref="PageBreakType.None"/>.
+    /// </param>
+    public ReplaceItem(string text, PageBreakType splitValue = PageBreakType.None)
     {
         Text = text;
-    }
-    public ReplaceItem(string text, bool breakPage)
-    {
-        Text = text;
-        BreakPage = breakPage;
+        SplitValue = splitValue;
     }
 
+    /// <summary>
+    /// Получает текст, который будет вставлен вместо плейсхолдера.
+    /// </summary>
     public string Text { get; init; } = string.Empty;
-    public bool BreakPage { get; init; } = false;
 
+    /// <summary>
+    /// Получает тип разрыва или смены ориентации, который будет применён
+    /// после вставки текста.
+    /// </summary>
+    public PageBreakType SplitValue { get; init; } = PageBreakType.None;
 
-    // Неявное преобразование из ReplaceItem в string
-    //public static implicit operator string(ReplaceItem item) => item.Text;
-    // Явное преобразование из string в ReplaceItem
+    /// <summary>
+    /// Определяет явное преобразование из строки в <see cref="ReplaceItem"/>.
+    /// </summary>
+    /// <param name="text">Строка текста.</param>
+    /// <returns>Новый экземпляр <see cref="ReplaceItem"/> с указанным текстом и <see cref="PageBreakType.None"/>.</returns>
     public static explicit operator ReplaceItem(string text) => new() { Text = text };
 }