From 78e36d6b7660e16c2bbe619dc22ca9484a7366c4 Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Tue, 2 Jun 2026 13:48:29 -0400 Subject: [PATCH 01/11] feat: include XML documentation in NuGet package (#215) - Enable GenerateDocumentationFile in Directory.Build.props so all projects emit XML docs. - Add .xml to AllowedOutputExtensionsInPackageBuildOutputFolder in icu.net.csproj so the XML file is bundled into the NuGet package for every target framework. Co-Authored-By: Claude Sonnet 4.6 --- source/Directory.Build.props | 1 + source/icu.net/icu.net.csproj | 1 + 2 files changed, 2 insertions(+) diff --git a/source/Directory.Build.props b/source/Directory.Build.props index d4799101..0842e61a 100644 --- a/source/Directory.Build.props +++ b/source/Directory.Build.props @@ -19,6 +19,7 @@ See full changelog at https://github.com/sillsdev/icu-dotnet/blob/master/CHANGEL snupkg default true + true true $(MSBuildThisFileDirectory)/icu.net.snk diff --git a/source/icu.net/icu.net.csproj b/source/icu.net/icu.net.csproj index 9db1b2ce..bca8a949 100644 --- a/source/icu.net/icu.net.csproj +++ b/source/icu.net/icu.net.csproj @@ -4,6 +4,7 @@ icu.net icu.net is a C# Wrapper around ICU4C README.md + $(AllowedOutputExtensionsInPackageBuildOutputFolder);.xml From d1bfffb1b92503ec1461d6470877f9e4b265b3d7 Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Tue, 2 Jun 2026 13:56:01 -0400 Subject: [PATCH 02/11] fix: scope GenerateDocumentationFile to icu.net project only Moves GenerateDocumentationFile out of Directory.Build.props (which applies to all projects) and into icu.net.csproj, avoiding spurious CS1591 warnings in the test projects. Co-Authored-By: Claude Sonnet 4.6 --- source/Directory.Build.props | 1 - source/icu.net/icu.net.csproj | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Directory.Build.props b/source/Directory.Build.props index 0842e61a..d4799101 100644 --- a/source/Directory.Build.props +++ b/source/Directory.Build.props @@ -19,7 +19,6 @@ See full changelog at https://github.com/sillsdev/icu-dotnet/blob/master/CHANGEL snupkg default true - true true $(MSBuildThisFileDirectory)/icu.net.snk diff --git a/source/icu.net/icu.net.csproj b/source/icu.net/icu.net.csproj index bca8a949..3b7091f7 100644 --- a/source/icu.net/icu.net.csproj +++ b/source/icu.net/icu.net.csproj @@ -4,6 +4,7 @@ icu.net icu.net is a C# Wrapper around ICU4C README.md + true $(AllowedOutputExtensionsInPackageBuildOutputFolder);.xml From 2ffa5867ca6a414db0cd814c2eaa6408b21326cb Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Tue, 2 Jun 2026 15:59:37 -0400 Subject: [PATCH 03/11] docs: add CHANGELOG entry for XML docs in NuGet package Co-Authored-By: Claude Sonnet 4.6 --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 48ed0e84..b1587361 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/). ### Added +- NuGet package now includes the XML documentation file, enabling IntelliSense summaries in Visual Studio. - In Character class, added all enums from Unicode's uchar.h that were missing: UBidiPairedBracketType, UBlockCode, UEastAsianWidth, UPropertyNameChoice, UJoiningType, UJoiningGroup, UGraphemeClusterBreak, UWordBreakValues, USentenceBreak, ULineBreak, From d063fa36109474916b30495ea4664370382068cf Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Thu, 11 Jun 2026 13:18:18 -0400 Subject: [PATCH 04/11] Fix warnings --- source/icu.net/Character.cs | 2 ++ source/icu.net/Normalization/Normalizer2.cs | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/source/icu.net/Character.cs b/source/icu.net/Character.cs index 0372492f..8607370f 100644 --- a/source/icu.net/Character.cs +++ b/source/icu.net/Character.cs @@ -3,6 +3,7 @@ using System; using System.Globalization; +#pragma warning disable CS1591 namespace Icu { /// @@ -2619,3 +2620,4 @@ public static int ToUpper(int codePoint) } } +#pragma warning restore CS1591 diff --git a/source/icu.net/Normalization/Normalizer2.cs b/source/icu.net/Normalization/Normalizer2.cs index 9e121a1c..d93f4829 100644 --- a/source/icu.net/Normalization/Normalizer2.cs +++ b/source/icu.net/Normalization/Normalizer2.cs @@ -141,7 +141,7 @@ private Normalizer2(string packageName, string name, Mode mode) /// characters. In other words, a string containing this character can be normalized by /// processing portions up to this character and after this character independently. This /// is used for iterative normalization. Note that this operation may be significantly - /// slower than . + /// slower than . /// /// character to test /// true if c has a normalization boundary after it From 197adc0e145a93e6753ae421f95c4908c99271bf Mon Sep 17 00:00:00 2001 From: "D. Ror" Date: Wed, 10 Jun 2026 13:05:33 -0400 Subject: [PATCH 05/11] Suppress param warnings --- source/Directory.Build.props | 1 + 1 file changed, 1 insertion(+) diff --git a/source/Directory.Build.props b/source/Directory.Build.props index d4799101..13c8add3 100644 --- a/source/Directory.Build.props +++ b/source/Directory.Build.props @@ -6,6 +6,7 @@ $(MSBuildThisFileDirectory)\..\output prompt 4 + $(NoWarn);CS1573 SIL Global SIL Global Copyright © 2007-2026 SIL Global From 4008fc417e66fe1069c1ee2e8c13dc5a0ff9fb55 Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Thu, 11 Jun 2026 13:24:14 -0400 Subject: [PATCH 06/11] fix: correct malformed XML doc comment in Transliterator.cs Co-Authored-By: Claude Sonnet 4.6 --- source/icu.net/Transliterator.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/icu.net/Transliterator.cs b/source/icu.net/Transliterator.cs index 9965c351..201d0dc4 100644 --- a/source/icu.net/Transliterator.cs +++ b/source/icu.net/Transliterator.cs @@ -289,7 +289,7 @@ private Transliterator(SafeTransliteratorHandle handle) /// Transliterate . /// /// The text to transliterate - /// <The capacity for the buffer that holds the + /// The capacity for the buffer that holds the /// transliterated text, expressed as a multiplier of the text length. /// /// The transliterated text. If the initial buffer overflows, the method retries with a doubled buffer. From f11591173130e598591651c4b8b785e813232202 Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Thu, 11 Jun 2026 13:30:54 -0400 Subject: [PATCH 07/11] refactor: move CS1573 suppression to icu.net project CS1573 only fires when GenerateDocumentationFile is enabled, which is scoped to icu.net. Suppressing it in Directory.Build.props was applying it to all projects unnecessarily. Co-Authored-By: Claude Sonnet 4.6 --- source/Directory.Build.props | 1 - source/icu.net/icu.net.csproj | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Directory.Build.props b/source/Directory.Build.props index 13c8add3..d4799101 100644 --- a/source/Directory.Build.props +++ b/source/Directory.Build.props @@ -6,7 +6,6 @@ $(MSBuildThisFileDirectory)\..\output prompt 4 - $(NoWarn);CS1573 SIL Global SIL Global Copyright © 2007-2026 SIL Global diff --git a/source/icu.net/icu.net.csproj b/source/icu.net/icu.net.csproj index 3b7091f7..cbd20307 100644 --- a/source/icu.net/icu.net.csproj +++ b/source/icu.net/icu.net.csproj @@ -5,6 +5,7 @@ icu.net is a C# Wrapper around ICU4C README.md true + $(NoWarn);CS1573 $(AllowedOutputExtensionsInPackageBuildOutputFolder);.xml From f1c5045bafe2a27bffd31a443aceeb37cd55ece1 Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Thu, 11 Jun 2026 13:33:07 -0400 Subject: [PATCH 08/11] docs: add missing XML doc comments to 5 files Covers BreakEnumerator finalizer, CodepageConversion class, Wrapper.MinSupportedIcuVersion/MaxSupportedIcuVersion, MessageFormatter class/Dispose/Pattern, and ResourceBundle.Dispose. Co-Authored-By: Claude Sonnet 4.6 --- source/icu.net/BreakIterators/BreakEnumerator.cs | 1 + source/icu.net/CodepageConversion.cs | 3 +++ source/icu.net/IcuWrapper.cs | 2 ++ source/icu.net/MessageFormatter.cs | 7 +++++++ source/icu.net/ResourceBundle.cs | 2 ++ 5 files changed, 15 insertions(+) diff --git a/source/icu.net/BreakIterators/BreakEnumerator.cs b/source/icu.net/BreakIterators/BreakEnumerator.cs index d463d211..816a7ef3 100644 --- a/source/icu.net/BreakIterators/BreakEnumerator.cs +++ b/source/icu.net/BreakIterators/BreakEnumerator.cs @@ -34,6 +34,7 @@ private void Dispose(bool disposing) _breakIterator = null; } + /// Finalizer. Logs a debug warning if was not called. ~BreakEnumerator() { Debug.WriteLineIf(_breakIterator != null, $"Missing Dispose() for {GetType()}"); diff --git a/source/icu.net/CodepageConversion.cs b/source/icu.net/CodepageConversion.cs index 042b85a5..7b1f56d7 100644 --- a/source/icu.net/CodepageConversion.cs +++ b/source/icu.net/CodepageConversion.cs @@ -6,6 +6,9 @@ namespace Icu { + /// + /// Provides utilities for working with ICU codepage/encoding converters. + /// public static class CodepageConversion { /// diff --git a/source/icu.net/IcuWrapper.cs b/source/icu.net/IcuWrapper.cs index 00ffc68e..70f75e9c 100644 --- a/source/icu.net/IcuWrapper.cs +++ b/source/icu.net/IcuWrapper.cs @@ -16,7 +16,9 @@ namespace Icu /// public static class Wrapper { + /// The minimum ICU version supported by this library. public const int MinSupportedIcuVersion = 44; + /// The maximum ICU version supported by this library. public const int MaxSupportedIcuVersion = 90; #region Public Properties diff --git a/source/icu.net/MessageFormatter.cs b/source/icu.net/MessageFormatter.cs index e6a7e812..0a51bf5d 100644 --- a/source/icu.net/MessageFormatter.cs +++ b/source/icu.net/MessageFormatter.cs @@ -6,6 +6,10 @@ namespace Icu { + /// + /// Wraps ICU's MessageFormat, which provides locale-sensitive formatting of messages + /// containing dates, times, numbers, and other values. + /// public class MessageFormatter : IDisposable { private IntPtr _Formatter; @@ -46,6 +50,8 @@ public void Dispose() Dispose(true); } + /// Releases the unmanaged resources used by this instance. + /// true if called from ; false if called from the finalizer. protected void Dispose(bool disposing) { if (disposing) @@ -59,6 +65,7 @@ protected void Dispose(bool disposing) } #endregion + /// Gets the pattern string of this message formatter. public string Pattern { get diff --git a/source/icu.net/ResourceBundle.cs b/source/icu.net/ResourceBundle.cs index c2f3b392..05756179 100644 --- a/source/icu.net/ResourceBundle.cs +++ b/source/icu.net/ResourceBundle.cs @@ -50,6 +50,8 @@ public void Dispose() Dispose(true); } + /// Releases the unmanaged resources used by this instance. + /// true if called from ; false if called from the finalizer. protected void Dispose(bool disposing) { if (disposing) From 4842ce1ad59855652f66b2b374a05dd114e916dc Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Thu, 11 Jun 2026 13:40:33 -0400 Subject: [PATCH 09/11] docs: add missing XML doc comments to Timezone files Co-Authored-By: Claude Sonnet 4.6 --- source/icu.net/Timezone/Timezone.cs | 3 +++ source/icu.net/Timezone/USystemTimeZoneType.cs | 10 ++++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/source/icu.net/Timezone/Timezone.cs b/source/icu.net/Timezone/Timezone.cs index aea95d07..8dd29892 100644 --- a/source/icu.net/Timezone/Timezone.cs +++ b/source/icu.net/Timezone/Timezone.cs @@ -4,6 +4,9 @@ namespace Icu { + /// + /// Represents an ICU time zone and provides utilities for querying and converting time zone information. + /// public class TimeZone { private readonly string zoneId; diff --git a/source/icu.net/Timezone/USystemTimeZoneType.cs b/source/icu.net/Timezone/USystemTimeZoneType.cs index 495a4e35..eb76f166 100644 --- a/source/icu.net/Timezone/USystemTimeZoneType.cs +++ b/source/icu.net/Timezone/USystemTimeZoneType.cs @@ -1,11 +1,17 @@ -using System; - namespace Icu { + /// + /// Specifies the type of system time zones to enumerate, used as a filter in + /// . + /// + /// public enum USystemTimeZoneType { + /// Any system zones. Any, + /// Canonical system zones. Canonical, + /// Canonical system zones associated with actual locations. CanonicalLocation, } } From 9d2e3ec418dc5ba2fe0c0ffee9678b8a42e8b7d3 Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Thu, 11 Jun 2026 13:55:09 -0400 Subject: [PATCH 10/11] docs: add missing XML doc comments to Transliterator and fix Dispose docs Adds class, UTransDirection enum, and Dispose docs to Transliterator. Replaces hand-written Dispose() summaries with in BiDi, BreakIterator, Collator, and RegexMatcher. Co-Authored-By: Claude Sonnet 4.6 --- source/icu.net/BiDi/BiDi.cs | 4 +--- .../icu.net/BreakIterators/BreakIterator.cs | 4 +--- source/icu.net/Collation/Collator.cs | 7 ++----- source/icu.net/RegexMatcher.cs | 9 ++------ source/icu.net/Transliterator.cs | 21 +++++++++++++++++++ 5 files changed, 27 insertions(+), 18 deletions(-) diff --git a/source/icu.net/BiDi/BiDi.cs b/source/icu.net/BiDi/BiDi.cs index 3bf4bc3f..6a1b38b8 100644 --- a/source/icu.net/BiDi/BiDi.cs +++ b/source/icu.net/BiDi/BiDi.cs @@ -194,9 +194,7 @@ void Dispose(bool disposing) Dispose(false); } - /// - /// Dispose of managed/unmanaged resources. - /// + /// public void Dispose() { Dispose(true); diff --git a/source/icu.net/BreakIterators/BreakIterator.cs b/source/icu.net/BreakIterators/BreakIterator.cs index 650236b6..1058d764 100644 --- a/source/icu.net/BreakIterators/BreakIterator.cs +++ b/source/icu.net/BreakIterators/BreakIterator.cs @@ -454,9 +454,7 @@ private static bool AddToken(UBreakIteratorType type, int status) return false; } - /// - /// Dispose of managed/unmanaged resources. - /// + /// public void Dispose() { Dispose(true); diff --git a/source/icu.net/Collation/Collator.cs b/source/icu.net/Collation/Collator.cs index 4cfb3d4d..8d6eba03 100644 --- a/source/icu.net/Collation/Collator.cs +++ b/source/icu.net/Collation/Collator.cs @@ -230,7 +230,7 @@ private static void SetInternalOriginalStringField(SortKey sortKey, string origi originalString); } - private static void SetInternalFieldForPublicProperty( + private static void SetInternalFieldForPublicProperty( T instance, string propertyName, string frameworkInternalFieldName, @@ -366,10 +366,7 @@ public static void GetSortKeyBound(byte[] sortKey, UColBoundMode boundType, ref #region IDisposable Support - /// - /// Dispose of managed/unmanaged resources. - /// Allow any inheriting classes to dispose of manage - /// + /// public void Dispose() { Dispose(true); diff --git a/source/icu.net/RegexMatcher.cs b/source/icu.net/RegexMatcher.cs index f52d2f54..0641541a 100644 --- a/source/icu.net/RegexMatcher.cs +++ b/source/icu.net/RegexMatcher.cs @@ -1,16 +1,13 @@ // Copyright (c) 2017 JEPA // This software is licensed under the MIT license (http://opensource.org/licenses/MIT) using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; namespace Icu { /// /// Regular Expression Matcher /// - public class RegexMatcher: IDisposable + public class RegexMatcher : IDisposable { /// /// Constants for Regular Expression Match Modes. @@ -149,9 +146,7 @@ public bool Matches(string str) return Matches(-1); } - /// - /// Dispose of managed/unmanaged resources. - /// + /// public void Dispose() { Dispose(true); diff --git a/source/icu.net/Transliterator.cs b/source/icu.net/Transliterator.cs index 201d0dc4..3d0de26e 100644 --- a/source/icu.net/Transliterator.cs +++ b/source/icu.net/Transliterator.cs @@ -8,11 +8,29 @@ namespace Icu { + /// + /// Wraps ICU's transliteration engine, which converts text from one script or encoding to another. + /// public class Transliterator : IDisposable { + /// + /// Direction constant indicating the direction in a transliterator, e.g., the forward or + /// reverse rules of a RuleBasedTransliterator. + /// + /// public enum UTransDirection { + /// + /// Transliterates from <source> to <target> for a transliterator with ID + /// <source>-<target>. For a transliterator opened using a rule, means + /// forward direction rules, e.g., A > B. + /// Forward, + /// + /// Transliterates from <target> to <source> for a transliterator with ID + /// <source>-<target>. For a transliterator opened using a rule, means + /// reverse direction rules, e.g., A < B. + /// Reverse } @@ -343,6 +361,8 @@ public string Transliterate(string text, int textCapacityMultiplier = 3) } #region Disposable pattern + /// Releases the resources used by this instance. + /// true if called from ; false if called during finalization. protected virtual void Dispose(bool disposing) { if (disposing) @@ -351,6 +371,7 @@ protected virtual void Dispose(bool disposing) } } + /// public void Dispose() { Dispose(true); From 79f5d1ebd7b2adce55c236923fce6ee3f54f089a Mon Sep 17 00:00:00 2001 From: Danny Rorabaugh Date: Thu, 11 Jun 2026 13:59:35 -0400 Subject: [PATCH 11/11] docs: fix copy-paste error in RegexMatcher.Dispose(bool) summary Co-Authored-By: Claude Sonnet 4.6 --- source/icu.net/MessageFormatter.cs | 2 +- source/icu.net/RegexMatcher.cs | 2 +- source/icu.net/ResourceBundle.cs | 2 +- source/icu.net/Transliterator.cs | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/icu.net/MessageFormatter.cs b/source/icu.net/MessageFormatter.cs index 0a51bf5d..62632fe3 100644 --- a/source/icu.net/MessageFormatter.cs +++ b/source/icu.net/MessageFormatter.cs @@ -50,7 +50,7 @@ public void Dispose() Dispose(true); } - /// Releases the unmanaged resources used by this instance. + /// Releases the resources used by MessageFormatter. /// true if called from ; false if called from the finalizer. protected void Dispose(bool disposing) { diff --git a/source/icu.net/RegexMatcher.cs b/source/icu.net/RegexMatcher.cs index 0641541a..30130063 100644 --- a/source/icu.net/RegexMatcher.cs +++ b/source/icu.net/RegexMatcher.cs @@ -154,7 +154,7 @@ public void Dispose() } /// - /// Releases the resources used by BreakIterator. + /// Releases the resources used by RegexMatcher. /// /// true to release managed and unmanaged /// resources; false to release only unmanaged resources. diff --git a/source/icu.net/ResourceBundle.cs b/source/icu.net/ResourceBundle.cs index 05756179..a9874383 100644 --- a/source/icu.net/ResourceBundle.cs +++ b/source/icu.net/ResourceBundle.cs @@ -50,7 +50,7 @@ public void Dispose() Dispose(true); } - /// Releases the unmanaged resources used by this instance. + /// Releases the resources used by ResourceBundle. /// true if called from ; false if called from the finalizer. protected void Dispose(bool disposing) { diff --git a/source/icu.net/Transliterator.cs b/source/icu.net/Transliterator.cs index 3d0de26e..f837b6af 100644 --- a/source/icu.net/Transliterator.cs +++ b/source/icu.net/Transliterator.cs @@ -361,7 +361,7 @@ public string Transliterate(string text, int textCapacityMultiplier = 3) } #region Disposable pattern - /// Releases the resources used by this instance. + /// Releases the resources used by Transliterator. /// true if called from ; false if called during finalization. protected virtual void Dispose(bool disposing) {