Add XML documentation for all public methods in HtmlUtil.cs

Update the HtmlUtil.cs file to include comprehensive XML documentation for all public methods. This enhances code readability and provides detailed explanations for each method's functionality, parameters, and return values.

Signed-off-by: Ivandro Jao <Ivandrofly@gmail.com>

src/libse/Common/HtmlUtil.cs

@@ -367,6 +367,12 @@ namespace Nikse.SubtitleEdit.Core.Common
             return encoded.ToString();
         }
 
+        /// <summary>
+        /// Remove all HTML tags from the input string, optionally including SSA tags.
+        /// </summary>
+        /// <param name="input">The input string that may contain HTML tags.</param>
+        /// <param name="alsoSsaTags">A boolean value indicating whether SSA tags should also be removed.</param>
+        /// <returns>A new string with all HTML tags removed, and optionally SSA tags removed.</returns>
         public static string RemoveHtmlTags(string input, bool alsoSsaTags = false)
         {
             if (input == null || input.Length < 3)
@@ -523,6 +529,11 @@ namespace Nikse.SubtitleEdit.Core.Common
             return new string(array, 0, arrayIndex);
         }
 
+        /// <summary>
+        /// Determines whether the specified text is a URL.
+        /// </summary>
+        /// <param name="text">The text to evaluate.</param>
+        /// <returns>True if the text is considered a URL, otherwise false.</returns>
         public static bool IsUrl(string text)
         {
             if (string.IsNullOrWhiteSpace(text) || text.Length < 6 || text.IndexOf('.') < 0 || text.IndexOf(' ') >= 0)
@@ -546,6 +557,11 @@ namespace Nikse.SubtitleEdit.Core.Common
             return false;
         }
 
+        /// <summary>
+        /// Determines if the provided text starts with a URL-like string.
+        /// </summary>
+        /// <param name="text">The text to examine.</param>
+        /// <returns>True if the text starts with a URL-like string; otherwise, false.</returns>
         public static bool StartsWithUrl(string text)
         {
             if (string.IsNullOrWhiteSpace(text))
@@ -564,6 +580,11 @@ namespace Nikse.SubtitleEdit.Core.Common
 
         private static readonly string[] UppercaseTags = { "<I>", "<U>", "<B>", "<FONT", "</I>", "</U>", "</B>", "</FONT>" };
 
+        /// <summary>
+        /// Converts all uppercase HTML tags in the input string to lowercase.
+        /// </summary>
+        /// <param name="input">The input string containing HTML tags to be converted.</param>
+        /// <returns>A new string with all uppercase HTML tags converted to lowercase.</returns>
         public static string FixUpperTags(string input)
         {
             if (string.IsNullOrEmpty(input) || input.IndexOf('<') < 0)
@@ -588,6 +609,11 @@ namespace Nikse.SubtitleEdit.Core.Common
             return text;
         }
 
+        /// <summary>
+        /// Determines if the provided text contains formattable content not enclosed within HTML-like tags.
+        /// </summary>
+        /// <param name="text">The input text to be checked.</param>
+        /// <returns>True if the text contains any formattable content (letters or digits) outside of HTML-like tags; otherwise, false.</returns>
         public static bool IsTextFormattable(in string text)
         {
             if (string.IsNullOrEmpty(text))
@@ -642,6 +668,11 @@ namespace Nikse.SubtitleEdit.Core.Common
             "< / i>", "</I>", "< / I >", "< /I>", "</ I>", "< /I >", "</I >", "</ I >", "< / I>", "</i<", "</I<", "</I>"
         };
 
+        /// <summary>
+        /// Fix invalid or improperly formatted italic tags in the input HTML string.
+        /// </summary>
+        /// <param name="input">The input HTML string to process.</param>
+        /// <returns>A string with corrected italic tags.</returns>
         public static string FixInvalidItalicTags(string input)
         {
             var text = input;
@@ -1000,6 +1031,14 @@ namespace Nikse.SubtitleEdit.Core.Common
             return preTags + text;
         }
 
+        /// <summary>
+        /// Toggles the specified HTML or SSA/ASS tag on or off in the provided text.
+        /// </summary>
+        /// <param name="input">The input string to apply the tag toggle.</param>
+        /// <param name="tag">The HTML or SSA/ASS tag to be toggled.</param>
+        /// <param name="wholeLine">Specifies whether the whole line should be toggled or just part of it.</param>
+        /// <param name="assa">Indicates whether the text contains SSA/ASS tags.</param>
+        /// <returns>A new string with the specified tag toggled.</returns>
         public static string ToggleTag(string input, string tag, bool wholeLine, bool assa)
         {
             var text = input;
@@ -1060,6 +1099,14 @@ namespace Nikse.SubtitleEdit.Core.Common
             return text;
         }
 
+        /// <summary>
+        /// Determines if the specified tag is present in the input HTML or SSA/ASS string.
+        /// </summary>
+        /// <param name="input">The input string to search for the specified tag.</param>
+        /// <param name="tag">The HTML or SSA/ASS tag to check for.</param>
+        /// <param name="wholeLine">Specifies whether the search should consider the whole line.</param>
+        /// <param name="assa">Indicates if the input string is in SSA/ASS format.</param>
+        /// <returns>True if the tag is present in the input; otherwise, false.</returns>
         public static bool IsTagOn(string input, string tag, bool wholeLine, bool assa)
         {
             var text = input;
@@ -1079,6 +1126,14 @@ namespace Nikse.SubtitleEdit.Core.Common
                    text.IndexOf("</" + tag + ">", StringComparison.OrdinalIgnoreCase) >= 0;
         }
 
+        /// <summary>
+        /// Applies the specified HTML or ASSA tag to the input string.
+        /// </summary>
+        /// <param name="input">The input string to which the tag will be applied.</param>
+        /// <param name="tag">The tag to apply to the input string.</param>
+        /// <param name="wholeLine">If true, the tag is applied to the entire line; otherwise, the tag is applied to a portion of the line.</param>
+        /// <param name="assa">If true, the tag is treated as an ASSA tag; otherwise, it is treated as an HTML tag.</param>
+        /// <returns>A new string with the specified tag applied.</returns>
         public static string TagOn(string input, string tag, bool wholeLine, bool assa)
         {
             var text = input;
@@ -1125,6 +1180,14 @@ namespace Nikse.SubtitleEdit.Core.Common
             return text;
         }
 
+        /// <summary>
+        /// Remove the specified HTML tag from the input string.
+        /// </summary>
+        /// <param name="input">The input string containing HTML tags.</param>
+        /// <param name="tag">The HTML tag to be removed.</param>
+        /// <param name="wholeLine">Indicates whether the operation applies to the whole line.</param>
+        /// <param name="assa">Indicates whether ASSA (Advanced SubStation Alpha) tags are used.</param>
+        /// <returns>A new string with the specified tag removed.</returns>
         public static string TagOff(string input, string tag, bool wholeLine, bool assa)
         {
             var text = input;
@@ -1174,6 +1237,12 @@ namespace Nikse.SubtitleEdit.Core.Common
             return text;
         }
 
+        /// <summary>
+        /// Converts a string representation of a color to a Color object. The string can be in various formats such as
+        /// "rgb(r, g, b)", "rgba(r, g, b, a)", or a hex color string like "#RRGGBB" or "#RRGGBBAA".
+        /// </summary>
+        /// <param name="s">The string representation of the color.</param>
+        /// <returns>A Color object corresponding to the input string. If the string cannot be parsed, the default color is white.</returns
         public static Color GetColorFromString(string s)
         {
             try
@@ -1229,6 +1298,11 @@ namespace Nikse.SubtitleEdit.Core.Common
             }
         }
 
+        /// <summary>
+        /// Remove color tags from the input string, adjusting for potentially surrounding font tags.
+        /// </summary>
+        /// <param name="input">The string from which to remove color tags.</param>
+        /// <returns>A new string with color tags removed.</returns>
         public static string RemoveColorTags(string input)
         {
             var r = new Regex("[ ]*(COLOR|color|Color)=[\"']*[#\\dA-Za-z]*[\"']*[ ]*");
@@ -1325,6 +1399,11 @@ namespace Nikse.SubtitleEdit.Core.Common
             return s;
         }
 
+        /// <summary>
+        /// Removes ASS and SSA alignment tags from the given string.
+        /// </summary>
+        /// <param name="s">The input string from which to remove the alignment tags.</param>
+        /// <returns>A new string without ASS and SSA alignment tags.</returns>
         public static string RemoveAssAlignmentTags(string s)
         {
             return s.Replace("{\\an1}", string.Empty) // ASS tags alone
@@ -1378,6 +1457,11 @@ namespace Nikse.SubtitleEdit.Core.Common
                 .Replace("{\\a9}", string.Empty);
         }
 
+        /// <summary>
+        /// Remove color tags specific to Advanced SubStation Alpha (ASSA) format from the input string.
+        /// </summary>
+        /// <param name="input">The input string potentially containing ASSA color tags.</param>
+        /// <returns>A new string with all ASSA color tags removed.</returns>
         public static string RemoveAssaColor(string input)
         {
             var text = input;
@@ -1389,6 +1473,11 @@ namespace Nikse.SubtitleEdit.Core.Common
             return text;
         }
 
+        /// <summary>
+        /// Gets the closing HTML tag for the specified opening tag.
+        /// </summary>
+        /// <param name="tag">The opening HTML tag to find the closing pair for.</param>
+        /// <returns>The closing HTML tag corresponding to the specified opening tag.</returns>
         public static string GetClosingPair(string tag)
         {
             switch (tag)
@@ -1400,10 +1489,25 @@ namespace Nikse.SubtitleEdit.Core.Common
             return tag.StartsWith("<font ", StringComparison.Ordinal) ? "</font>" : string.Empty;
         }
 
+        /// <summary>
+        /// Get the corresponding closing character for a given opening character.
+        /// </summary>
+        /// <param name="ch">The opening character to find the closing pair for.</param>
+        /// <returns>The corresponding closing character.</returns>
         public static char GetClosingPair(char ch) => ch == '<' ? '>' : '}';
 
+        /// <summary>
+        /// Determines if the provided HTML tag is an opening tag.
+        /// </summary>
+        /// <param name="tag">The HTML tag to check.</param>
+        /// <returns>True if the tag is an opening tag, otherwise false.</returns
         public static bool IsOpenTag(string tag) => tag.Length > 1 && tag[1] != '/';
 
+        /// <summary>
+        /// Determines whether the specified character is a start tag symbol for HTML or similar markup.
+        /// </summary>
+        /// <param name="ch">The character to check.</param>
+        /// <returns>True if the character is a start tag symbol; otherwise, false.</returns>
         public static bool IsStartTagSymbol(char ch) => ch == '<' || ch == '{';
     }
 }