From 80d20fbb77faeb56af95dbdf260db3933d6b1ca7 Mon Sep 17 00:00:00 2001 From: Ivandro Jao Date: Fri, 13 Sep 2024 15:14:12 +0100 Subject: [PATCH] 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 --- src/libse/Common/HtmlUtil.cs | 110 ++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 3 deletions(-) diff --git a/src/libse/Common/HtmlUtil.cs b/src/libse/Common/HtmlUtil.cs index 180a1f341..2c4d63438 100644 --- a/src/libse/Common/HtmlUtil.cs +++ b/src/libse/Common/HtmlUtil.cs @@ -367,6 +367,12 @@ namespace Nikse.SubtitleEdit.Core.Common return encoded.ToString(); } + /// + /// Remove all HTML tags from the input string, optionally including SSA tags. + /// + /// The input string that may contain HTML tags. + /// A boolean value indicating whether SSA tags should also be removed. + /// A new string with all HTML tags removed, and optionally SSA tags removed. 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); } + /// + /// Determines whether the specified text is a URL. + /// + /// The text to evaluate. + /// True if the text is considered a URL, otherwise false. 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; } + /// + /// Determines if the provided text starts with a URL-like string. + /// + /// The text to examine. + /// True if the text starts with a URL-like string; otherwise, false. public static bool StartsWithUrl(string text) { if (string.IsNullOrWhiteSpace(text)) @@ -564,6 +580,11 @@ namespace Nikse.SubtitleEdit.Core.Common private static readonly string[] UppercaseTags = { "", "", "", "", "", "", "" }; + /// + /// Converts all uppercase HTML tags in the input string to lowercase. + /// + /// The input string containing HTML tags to be converted. + /// A new string with all uppercase HTML tags converted to lowercase. public static string FixUpperTags(string input) { if (string.IsNullOrEmpty(input) || input.IndexOf('<') < 0) @@ -588,6 +609,11 @@ namespace Nikse.SubtitleEdit.Core.Common return text; } + /// + /// Determines if the provided text contains formattable content not enclosed within HTML-like tags. + /// + /// The input text to be checked. + /// True if the text contains any formattable content (letters or digits) outside of HTML-like tags; otherwise, false. public static bool IsTextFormattable(in string text) { if (string.IsNullOrEmpty(text)) @@ -641,7 +667,12 @@ namespace Nikse.SubtitleEdit.Core.Common "< / i >", "< /i>", "", "< /i >", "", "", "< / i>", "", "< / I >", "< /I>", "", "< /I >", "", "", "< / I>", "" }; - + + /// + /// Fix invalid or improperly formatted italic tags in the input HTML string. + /// + /// The input HTML string to process. + /// A string with corrected italic tags. public static string FixInvalidItalicTags(string input) { var text = input; @@ -1000,6 +1031,14 @@ namespace Nikse.SubtitleEdit.Core.Common return preTags + text; } + /// + /// Toggles the specified HTML or SSA/ASS tag on or off in the provided text. + /// + /// The input string to apply the tag toggle. + /// The HTML or SSA/ASS tag to be toggled. + /// Specifies whether the whole line should be toggled or just part of it. + /// Indicates whether the text contains SSA/ASS tags. + /// A new string with the specified tag toggled. 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; } + /// + /// Determines if the specified tag is present in the input HTML or SSA/ASS string. + /// + /// The input string to search for the specified tag. + /// The HTML or SSA/ASS tag to check for. + /// Specifies whether the search should consider the whole line. + /// Indicates if the input string is in SSA/ASS format. + /// True if the tag is present in the input; otherwise, false. 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("", StringComparison.OrdinalIgnoreCase) >= 0; } + /// + /// Applies the specified HTML or ASSA tag to the input string. + /// + /// The input string to which the tag will be applied. + /// The tag to apply to the input string. + /// If true, the tag is applied to the entire line; otherwise, the tag is applied to a portion of the line. + /// If true, the tag is treated as an ASSA tag; otherwise, it is treated as an HTML tag. + /// A new string with the specified tag applied. 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; } + /// + /// Remove the specified HTML tag from the input string. + /// + /// The input string containing HTML tags. + /// The HTML tag to be removed. + /// Indicates whether the operation applies to the whole line. + /// Indicates whether ASSA (Advanced SubStation Alpha) tags are used. + /// A new string with the specified tag removed. 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; } + /// + /// 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". + /// + /// The string representation of the color. + /// A Color object corresponding to the input string. If the string cannot be parsed, the default color is white. + /// Remove color tags from the input string, adjusting for potentially surrounding font tags. + /// + /// The string from which to remove color tags. + /// A new string with color tags removed. 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; } + /// + /// Removes ASS and SSA alignment tags from the given string. + /// + /// The input string from which to remove the alignment tags. + /// A new string without ASS and SSA alignment tags. 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); } + /// + /// Remove color tags specific to Advanced SubStation Alpha (ASSA) format from the input string. + /// + /// The input string potentially containing ASSA color tags. + /// A new string with all ASSA color tags removed. public static string RemoveAssaColor(string input) { var text = input; @@ -1388,7 +1472,12 @@ namespace Nikse.SubtitleEdit.Core.Common text = Regex.Replace(text, "\\\\1c&[abcdefghABCDEFGH\\d]*&", string.Empty); return text; } - + + /// + /// Gets the closing HTML tag for the specified opening tag. + /// + /// The opening HTML tag to find the closing pair for. + /// The closing HTML tag corresponding to the specified opening tag. public static string GetClosingPair(string tag) { switch (tag) @@ -1399,11 +1488,26 @@ namespace Nikse.SubtitleEdit.Core.Common } return tag.StartsWith("" : string.Empty; } - + + /// + /// Get the corresponding closing character for a given opening character. + /// + /// The opening character to find the closing pair for. + /// The corresponding closing character. public static char GetClosingPair(char ch) => ch == '<' ? '>' : '}'; + /// + /// Determines if the provided HTML tag is an opening tag. + /// + /// The HTML tag to check. + /// True if the tag is an opening tag, otherwise false. tag.Length > 1 && tag[1] != '/'; + /// + /// Determines whether the specified character is a start tag symbol for HTML or similar markup. + /// + /// The character to check. + /// True if the character is a start tag symbol; otherwise, false. public static bool IsStartTagSymbol(char ch) => ch == '<' || ch == '{'; } }