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 @@ public static string EncodeNumeric(string source)
             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 @@ private static string RemoveCommonHtmlTags(string s)
             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 @@ public static bool IsUrl(string text)
             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 @@ public static bool StartsWithUrl(string text)
 
         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 @@ public static string FixUpperTags(string input)
             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))
@@ -641,7 +667,12 @@ public static bool IsTextFormattable(in string text)
             "< / i >", "< /i>", "</ i>", "< /i >", "</i >", "</ i >",
             "< / 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 @@ int CalculateEarlyInsertIndex(string s)
             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 @@ public static string ToggleTag(string input, string tag, bool wholeLine, bool as
             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 @@ public static bool IsTagOn(string input, string tag, bool wholeLine, bool assa)
                    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 @@ public static string TagOn(string input, string tag, bool wholeLine, bool assa)
             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 @@ public static string TagOff(string input, string tag, bool wholeLine, bool assa)
             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 @@ public static Color GetColorFromString(string s)
             }
         }
 
+        /// <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 @@ public static string RemoveFontName(string input)
             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 @@ public static string RemoveAssAlignmentTags(string s)
                 .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;
@@ -1388,7 +1472,12 @@ public static string RemoveAssaColor(string input)
             text = Regex.Replace(text, "\\\\1c&[abcdefghABCDEFGH\\d]*&", string.Empty);
             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)
@@ -1399,11 +1488,26 @@ public static string GetClosingPair(string tag)
             }
             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 == '{';
     }
 }