Improve documentation

src/libse/Common/ColorUtils.cs

@@ -5,6 +5,13 @@ namespace Nikse.SubtitleEdit.Core.Common
 {
     public static class ColorUtils
     {
+        /// <summary>
+        /// Blends two colors by a specified percentage.
+        /// </summary>
+        /// <param name="baseColor">The base color to blend from.</param>
+        /// <param name="targetColor">The target color to blend to.</param>
+        /// <param name="percentage">The blending percentage. A value between 0 and 1. Defaults to 0.5.</param>
+        /// <returns>A new <see cref="Color"/> that is the result of blending the base and target colors.</returns>
         public static Color Blend(this Color baseColor, Color targetColor, double percentage = 0.5)
         {
             percentage = Math.Abs(percentage);
@@ -21,13 +28,30 @@ public static Color Blend(this Color baseColor, Color targetColor, double percen
                 Lerp(baseColor.B, targetColor.B, percentage));
         }
 
+        /// <summary>
+        /// Linearly interpolates between two integer color components by a specified percentage.
+        /// </summary>
+        /// <param name="baseColor">The starting color component value.</param>
+        /// <param name="targetColor">The target color component value.</param>
+        /// <param name="percentage">The interpolation percentage. A value between 0 and 1.</param>
+        /// <returns>An integer representing the interpolated color component value.</returns>
         private static int Lerp(int baseColor, int targetColor, double percentage)
         {
             return (byte)Math.Round(baseColor  + percentage * (targetColor - baseColor));
         }
-
+
+        /// <summary>
+        /// Calculates the relative luminance of a color, which is a measure of the perceived brightness.
+        /// </summary>
+        /// <param name="color">The color for which to calculate luminance.</param>
+        /// <returns>A double value representing the luminance of the color, ranging from 0 (darkest) to 1 (brightest).</returns>
         public static double Luminance(this Color color) => (color.R * 0.299 + color.G * 0.587 + color.B * 0.114) / 255;
-
+
+        /// <summary>
+        /// Calculates a color with the opposing luminance of the given color.
+        /// </summary>
+        /// <param name="baseColor">The base color for which to calculate the opposing luminance color.</param>
+        /// <returns>A new <see cref="Color"/> that has the opposing luminance compared to the base color.</returns>
         public static Color OpposingLuminanceColor(this Color baseColor)
         {
             var luminance = baseColor.Luminance();

src/libse/Common/CsvUtil.cs

@@ -3,8 +3,19 @@
 
 namespace Nikse.SubtitleEdit.Core.Common
 {
+    /// <summary>
+    /// Provides utility methods for working with CSV (Comma-separated values) data.
+    /// </summary>
     public static class CsvUtil
     {
+        /// <summary>
+        /// Splits a CSV line into an array of strings based on the provided parameters.
+        /// Handles quoted and non-quoted CSV entries.
+        /// </summary>
+        /// <param name="line">The CSV line to be split into parts.</param>
+        /// <param name="quoteOn">A boolean indicating whether to handle quoted entries.</param>
+        /// <param name="continuation">An out parameter indicating if the line ends with an open quote.</param>
+        /// <returns>An array of strings representing the split parts of the CSV line.</returns>
         public static string[] CsvSplit(string line, bool quoteOn, out bool continuation)
         {
             var lines = new List<string>();

src/libse/Common/CultureExtensions.cs

@@ -5,10 +5,10 @@ namespace Nikse.SubtitleEdit.Core.Common
     public static class CultureExtensions
     {
         /// <summary>
-        /// Get three letter ISO code from CultureInfo object (three letter ISO code seems to be blank sometimes on Mono/Wine).
+        /// Get three-letter ISO code from CultureInfo object (three-letter ISO code seems to be blank sometimes on Mono/Wine).
         /// </summary>
         /// <param name="cultureInfo">CultureInfo object</param>
-        /// <returns>Three letter ISO language code, if failure then string.Empty is returned.</returns>
+        /// <returns>Three-letter ISO language code, if failure then string.Empty is returned.</returns>
         public static string GetThreeLetterIsoLanguageName(this CultureInfo cultureInfo)
         {
             if (cultureInfo == null)

src/libse/Common/DialogSplitMerge.cs

@@ -5,26 +5,107 @@
 
 namespace Nikse.SubtitleEdit.Core.Common
 {
+    /// <summary>
+    /// DialogSplitMerge class provides functionality to handle dialog splits and merges,
+    /// allowing for customized dialog styles and continuation styles within subtitles.
+    /// </summary>
     public class DialogSplitMerge
     {
+        /// <summary>
+        /// Gets or sets the style of dialog to be used for splitting and merging subtitles.
+        /// The <see cref="DialogStyle"/> determines how dashes and spaces are handled in dialogs.
+        /// </summary>
+        /// <remarks>
+        /// Possible values for <see cref="DialogStyle"/> are defined in the <see cref="DialogType"/> enum and include:
+        /// - DashBothLinesWithSpace
+        /// - DashBothLinesWithoutSpace
+        /// - DashSecondLineWithSpace
+        /// - DashSecondLineWithoutSpace
+        /// </remarks>
         public DialogType DialogStyle { get; set; }
+
+        /// <summary>
+        /// Gets or sets the continuation style used for handling subtitle lines that continue across multiple dialogues.
+        /// The <see cref="ContinuationStyle"/> determines the punctuation and formatting applied to these continuing lines.
+        /// </summary>
+        /// <remarks>
+        /// Possible values for <see cref="ContinuationStyle"/> are defined in the <see cref="Nikse.SubtitleEdit.Core.Enums.ContinuationStyle"/> enum and include options such as:
+        /// - None
+        /// - NoneTrailingDots
+        /// - NoneLeadingTrailingDots
+        /// - NoneTrailingEllipsis
+        /// - NoneLeadingTrailingEllipsis
+        /// - OnlyTrailingDots
+        /// - LeadingTrailingDots
+        /// - OnlyTrailingEllipsis
+        /// - LeadingTrailingEllipsis
+        /// - LeadingTrailingDash
+        /// - LeadingTrailingDashDots
+        /// - Custom
+        /// </remarks>
         public ContinuationStyle ContinuationStyle { get; set; }
+
+        /// <summary>
+        /// Gets or sets the two-letter ISO 639-1 language code.
+        /// The <see cref="TwoLetterLanguageCode"/> is used to determine language-specific processing behavior.
+        /// </summary>
+        /// <remarks>
+        /// This property is important for functions that require language-specific rules,
+        /// such as detecting if a language typically omits periods at the end of sentences.
+        /// </remarks>
         public string TwoLetterLanguageCode { get; set; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether to skip checking the line endings when
+        /// performing dialog split and merge operations.
+        /// </summary>
+        /// <remarks>
+        /// When set to <c>true</c>, dialog split and merge operations will not enforce line ending checks,
+        /// which may be required for certain languages or specific subtitle correction scenarios.
+        /// </remarks>
         public bool SkipLineEndingCheck { get; set; }
 
+        /// <summary>
+        /// Retrieves the dash character used for dialog formatting.
+        /// </summary>
+        /// <returns>A character representing the dash style used in dialogs.</returns>
         private static char GetDashChar() => '-';
+
+        /// <summary>
+        /// Retrieves the alternate dash character used for dialog formatting.
+        /// </summary>
+        /// <returns>A character representing an alternate dash style used in dialogs.</returns>
         private static char GetAlternateDashChar() => '‐'; // Unicode En Dash (\u2010)
 
+        /// <summary>
+        /// Fixes the dashes and adjusts the surrounding spacing based on the provided input text, current paragraph, and previous paragraph.
+        /// </summary>
+        /// <param name="input">The dialog text input to be processed.</param>
+        /// <param name="p">The current paragraph containing the dialog text.</param>
+        /// <param name="prev">The previous paragraph which may affect the style of the current dialog.</param>
+        /// <returns>Formatted dialog text with corrected dashes and appropriate spacing.</returns>
         public string FixDashesAndSpaces(string input)
         {
             return FixSpaces(FixDashes(input));
         }
 
+        /// <summary>
+        /// Fixes the dashes and adjusts the surrounding spacing based on the given paragraphs.
+        /// </summary>
+        /// <param name="input">The dialog text input to be processed.</param>
+        /// <param name="p">The current paragraph containing the dialog text.</param>
+        /// <param name="prev">The previous paragraph which may affect the style of the current dialog.</param>
+        /// <returns>Formatted dialog text with corrected dashes and appropriate spacing.</returns>
         public string FixDashesAndSpaces(string input, Paragraph p, Paragraph prev)
         {
             return FixSpaces(FixDashes(input, p, prev));
         }
 
+        /// <summary>
+        /// Adjusts the spacing around dialog dashes based on the specified dialog style.
+        /// </summary>
+        /// <param name="input">The dialog text input that requires spacing adjustments.</param>
+        /// <returns>Formatted dialog text with correct spacing around dashes based on the dialog style.</returns>
         public string FixSpaces(string input)
         {
             var lines = input.SplitToLines();
@@ -92,6 +173,12 @@ public string FixSpaces(string input)
             return sb.ToString().TrimEnd();
         }
 
+        /// <summary>
+        /// Adds spaces around dialog lines based on the dialog style settings.
+        /// Processes each line of the input text and adjusts spaces around dashes appropriately.
+        /// </summary>
+        /// <param name="input">The input string containing dialog lines.</param>
+        /// <returns>Formatted dialog text with appropriate spaces added around dashes.</returns>
         public string AddSpaces(string input)
         {
             var lines = input.SplitToLines();
@@ -138,6 +225,11 @@ public string AddSpaces(string input)
             return sb.ToString().TrimEnd();
         }
 
+        /// <summary>
+        /// Removes unnecessary spaces from dialog lines based on the set dialog style.
+        /// </summary>
+        /// <param name="input">The dialog text from which spaces need to be removed.</param>
+        /// <returns>A string with spaces removed based on the dialog style configuration.</returns>
         public string RemoveSpaces(string input)
         {
             var lines = input.SplitToLines();
@@ -187,6 +279,14 @@ public string RemoveSpaces(string input)
             return sb.ToString().TrimEnd();
         }
 
+        /// <summary>
+        /// Fixes the dashes in the provided input text based on the dialog style and formatting rules
+        /// determined by the current paragraph and the previous paragraph.
+        /// </summary>
+        /// <param name="input">The dialog text input to be processed.</param>
+        /// <param name="p">The current paragraph containing the dialog text.</param>
+        /// <param name="prev">The previous paragraph which may affect the style of the current dialog.</param>
+        /// <returns>Formatted dialog text with corrected dashes according to the specified rules.</returns>
         public string FixDashes(string input, Paragraph p, Paragraph prev)
         {
             var lines = input.SplitToLines();
@@ -283,6 +383,11 @@ public string FixDashes(string input, Paragraph p, Paragraph prev)
             return sb.ToString().TrimEnd();
         }
 
+        /// <summary>
+        /// Fixes the dashes in the provided input dialog text based on predefined styles, ensuring proper format across lines.
+        /// </summary>
+        /// <param name="input">The dialog text input to be processed.</param>
+        /// <returns>Formatted dialog text with corrected dashes according to the specified style.</returns>
         public string FixDashes(string input)
         {
             var lines = input.SplitToLines();
@@ -379,6 +484,12 @@ public string FixDashes(string input)
             return sb.ToString().TrimEnd();
         }
 
+        /// <summary>
+        /// Inserts a starting dash in the provided text, at the specified line index.
+        /// </summary>
+        /// <param name="input">The text to be processed.</param>
+        /// <param name="lineIndex">The index of the line where the dash should be inserted.</param>
+        /// <returns>The text with the starting dash appropriately inserted.</returns>
         public string InsertStartDash(string input, int lineIndex)
         {
             var pre = GetStartTags(input);
@@ -397,6 +508,12 @@ public string InsertStartDash(string input, int lineIndex)
             return pre + GetLineStartFromDashStyle(lineIndex) + s.TrimStart();
         }
 
+        /// <summary>
+        /// Removes the starting dash from the input string, if present, and
+        /// adjusts the surrounding spaces while preserving any leading tags.
+        /// </summary>
+        /// <param name="input">The input text from which the starting dash needs to be removed.</param>
+        /// <returns>The input string without the starting dash, preserving leading tags and spaces.</returns>
         public static string RemoveStartDash(string input)
         {
             var pre = GetStartTags(input);
@@ -410,6 +527,11 @@ public static string RemoveStartDash(string input)
             return pre + s.TrimStart().TrimStart(GetDashChar(), GetAlternateDashChar()).TrimStart();
         }
 
+        /// <summary>
+        /// Generates a dialog style preview string based on the specified dialog type.
+        /// </summary>
+        /// <param name="dialogType">The type of dialog formatting to use for generating the preview.</param>
+        /// <returns>A formatted string representation of the dialog style preview.</returns>
         public static string GetDialogStylePreview(DialogType dialogType)
         {
             var line1 = "Lorem ipsum dolor sit amet.";
@@ -428,6 +550,11 @@ public static string GetDialogStylePreview(DialogType dialogType)
             }
         }
 
+        /// <summary>
+        /// Determines the dialog style based on the provided index.
+        /// </summary>
+        /// <param name="index">The index representing a specific dialog style.</param>
+        /// <returns>The corresponding DialogType based on the index provided.</returns>
         public static DialogType GetDialogStyleFromIndex(int index)
         {
             switch (index)
@@ -443,6 +570,11 @@ public static DialogType GetDialogStyleFromIndex(int index)
             }
         }
 
+        /// <summary>
+        /// Extracts and returns the starting tags (such as formatting tags) from the beginning of the given input string.
+        /// </summary>
+        /// <param name="input">The input string potentially containing tags at the beginning.</param>
+        /// <returns>A string containing all starting tags extracted from the input.</returns>
         private static string GetStartTags(string input)
         {
             var pre = new StringBuilder();
@@ -463,6 +595,11 @@ private static string GetStartTags(string input)
             return pre.ToString();
         }
 
+        /// <summary>
+        /// Determines whether a given list of lines represents a dialog based on specific rules and conditions.
+        /// </summary>
+        /// <param name="lines">A list of strings, where each string is a line of text to be evaluated.</param>
+        /// <returns>True if the lines represent a dialog, otherwise false.</returns>
         public bool IsDialog(List<string> lines)
         {
             if (lines.Count < 2 || lines.Count > 3)
@@ -526,7 +663,13 @@ public bool IsDialog(List<string> lines)
             return false;
         }
 
-
+        /// <summary>
+        /// Determines if the provided list of lines represents a dialog based on the given paragraphs.
+        /// </summary>
+        /// <param name="lines">A list of strings representing the lines of text to check.</param>
+        /// <param name="p">The current paragraph containing the text.</param>
+        /// <param name="prev">The previous paragraph which might influence the dialog style of the current paragraph.</param>
+        /// <returns>True if the text lines represent a dialog, otherwise false.</returns>
         public bool IsDialog(List<string> lines, Paragraph p, Paragraph prev)
         {
             if (lines.Count < 2 || lines.Count > 3)
@@ -589,6 +732,14 @@ public bool IsDialog(List<string> lines, Paragraph p, Paragraph prev)
             return false;
         }
 
+        /// <summary>
+        /// Determines if the provided lines represent a three-line dialog where the first line ends with a sentence-ending punctuation,
+        /// the second line starts with a dash, and the third line does not start with a dash.
+        /// </summary>
+        /// <param name="l0">The first line of the dialog.</param>
+        /// <param name="l1">The second line of the dialog.</param>
+        /// <param name="l2">The third line of the dialog.</param>
+        /// <returns>True if the lines represent a three-line dialog in the specified format, otherwise false.</returns>
         private bool IsDialogThreeLinesOneTwo(string l0, string l1, string l2)
         {
             return l0.HasSentenceEnding(TwoLetterLanguageCode) &&
@@ -597,6 +748,16 @@ private bool IsDialogThreeLinesOneTwo(string l0, string l1, string l2)
                    !(l2.TrimStart().StartsWith(GetDashChar()) || l2.TrimStart().StartsWith(GetAlternateDashChar()));
         }
 
+        /// <summary>
+        /// Checks if the given lines follow a specific dialog pattern where the first line does not end with a sentence,
+        /// the second line ends with a sentence, and the third line starts with a dash.
+        /// </summary>
+        /// <param name="l0">The first line of the dialog.</param>
+        /// <param name="l1">The second line of the dialog.</param>
+        /// <param name="l2">The third line of the dialog.</param>
+        /// <returns>
+        /// True if the lines match the specified three-line dialog pattern; otherwise, false.
+        /// </returns>
         private bool IsDialogThreeLinesTwoOne(string l0, string l1, string l2)
         {
             return !l0.HasSentenceEnding(TwoLetterLanguageCode) &&
@@ -605,6 +766,11 @@ private bool IsDialogThreeLinesTwoOne(string l0, string l1, string l2)
                    (l2.TrimStart().StartsWith(GetDashChar())) || l2.TrimStart().StartsWith(GetAlternateDashChar());
         }
 
+        /// <summary>
+        /// Determines the line start based on the dash style for the dialog and the index of the line.
+        /// </summary>
+        /// <param name="lineIndex">The index of the line in the dialog.</param>
+        /// <returns>A string representing the start of the line based on the dialog style and line index.</returns>
         private string GetLineStartFromDashStyle(int lineIndex)
         {
             switch (DialogStyle)