feat: include XML documentation in NuGet package (#215)

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,

source/icu.net/BiDi/BiDi.cs

@@ -194,9 +194,7 @@ void Dispose(bool disposing)
 			Dispose(false);
 		}
 
-		/// <summary>
-		/// Dispose of managed/unmanaged resources.
-		/// </summary>
+		/// <inheritdoc/>
 		public void Dispose()
 		{
 			Dispose(true);

source/icu.net/BreakIterators/BreakEnumerator.cs

@@ -34,6 +34,7 @@ private void Dispose(bool disposing)
 			_breakIterator = null;
 		}
 
+		/// <summary>Finalizer. Logs a debug warning if <see cref="Dispose()"/> was not called.</summary>
 		~BreakEnumerator()
 		{
 			Debug.WriteLineIf(_breakIterator != null, $"Missing Dispose() for {GetType()}");

source/icu.net/BreakIterators/BreakIterator.cs

@@ -454,9 +454,7 @@ private static bool AddToken(UBreakIteratorType type, int status)
 			return false;
 		}
 
-		/// <summary>
-		/// Dispose of managed/unmanaged resources.
-		/// </summary>
+		/// <inheritdoc/>
 		public void Dispose()
 		{
 			Dispose(true);

source/icu.net/Character.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Globalization;
 
+#pragma warning disable CS1591
 namespace Icu
 {
 	/// <summary>
@@ -2619,3 +2620,4 @@ public static int ToUpper(int codePoint)
 
 	}
 }
+#pragma warning restore CS1591

source/icu.net/CodepageConversion.cs

@@ -6,6 +6,9 @@
 
 namespace Icu
 {
+	/// <summary>
+	/// Provides utilities for working with ICU codepage/encoding converters.
+	/// </summary>
 	public static class CodepageConversion
 	{
 		/// <summary>

source/icu.net/Collation/Collator.cs

@@ -230,7 +230,7 @@ private static void SetInternalOriginalStringField(SortKey sortKey, string origi
 											  originalString);
 		}
 
-		private static void SetInternalFieldForPublicProperty<T,P>(
+		private static void SetInternalFieldForPublicProperty<T, P>(
 			T instance,
 			string propertyName,
 			string frameworkInternalFieldName,
@@ -366,10 +366,7 @@ public static void GetSortKeyBound(byte[] sortKey, UColBoundMode boundType, ref
 
 		#region IDisposable Support
 
-		/// <summary>
-		/// Dispose of managed/unmanaged resources.
-		/// Allow any inheriting classes to dispose of manage
-		/// </summary>
+		/// <inheritdoc/>
 		public void Dispose()
 		{
 			Dispose(true);

source/icu.net/IcuWrapper.cs

@@ -16,7 +16,9 @@ namespace Icu
 	/// </summary>
 	public static class Wrapper
 	{
+		/// <summary>The minimum ICU version supported by this library.</summary>
 		public const int MinSupportedIcuVersion = 44;
+		/// <summary>The maximum ICU version supported by this library.</summary>
 		public const int MaxSupportedIcuVersion = 90;
 
 		#region Public Properties

source/icu.net/MessageFormatter.cs

@@ -6,6 +6,10 @@
 
 namespace Icu
 {
+	/// <summary>
+	/// Wraps ICU's MessageFormat, which provides locale-sensitive formatting of messages
+	/// containing dates, times, numbers, and other values.
+	/// </summary>
 	public class MessageFormatter : IDisposable
 	{
 		private IntPtr _Formatter;
@@ -46,6 +50,8 @@ public void Dispose()
 			Dispose(true);
 		}
 
+		/// <summary>Releases the resources used by MessageFormatter.</summary>
+		/// <param name="disposing"><c>true</c> if called from <see cref="Dispose()"/>; <c>false</c> if called from the finalizer.</param>
 		protected void Dispose(bool disposing)
 		{
 			if (disposing)
@@ -59,6 +65,7 @@ protected void Dispose(bool disposing)
 		}
 		#endregion
 
+		/// <summary>Gets the pattern string of this message formatter.</summary>
 		public string Pattern
 		{
 			get

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 <see cref="hasBoundaryBefore"/>.
+		/// slower than <see cref="HasBoundaryBefore"/>.
 		/// </summary>
 		/// <param name="codePoint">character to test</param>
 		/// <returns><c>true</c> if c has a normalization boundary after it</returns>

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
 {
 	/// <summary>
 	/// Regular Expression Matcher
 	/// </summary>
-	public class RegexMatcher: IDisposable
+	public class RegexMatcher : IDisposable
 	{
 		/// <summary>
 		/// Constants for Regular Expression Match Modes.
@@ -149,17 +146,15 @@ public bool Matches(string str)
 			return Matches(-1);
 		}
 
-		/// <summary>
-		/// Dispose of managed/unmanaged resources.
-		/// </summary>
+		/// <inheritdoc/>
 		public void Dispose()
 		{
 			Dispose(true);
 			GC.SuppressFinalize(this);
 		}
 
 		/// <summary>
-		/// Releases the resources used by BreakIterator.
+		/// Releases the resources used by RegexMatcher.
 		/// </summary>
 		/// <param name="disposing">true to release managed and unmanaged
 		/// resources; false to release only unmanaged resources.</param>

source/icu.net/ResourceBundle.cs

@@ -50,6 +50,8 @@ public void Dispose()
 			Dispose(true);
 		}
 
+		/// <summary>Releases the resources used by ResourceBundle.</summary>
+		/// <param name="disposing"><c>true</c> if called from <see cref="Dispose()"/>; <c>false</c> if called from the finalizer.</param>
 		protected void Dispose(bool disposing)
 		{
 			if (disposing)

source/icu.net/Timezone/Timezone.cs

@@ -4,6 +4,9 @@
 
 namespace Icu
 {
+	/// <summary>
+	/// Represents an ICU time zone and provides utilities for querying and converting time zone information.
+	/// </summary>
 	public class TimeZone
 	{
 		private readonly string zoneId;

source/icu.net/Timezone/USystemTimeZoneType.cs

@@ -1,11 +1,17 @@
-using System;
-
 namespace Icu
 {
+	/// <summary>
+	/// Specifies the type of system time zones to enumerate, used as a filter in
+	/// <see cref="TimeZone.GetTimeZones(USystemTimeZoneType, string)"/>.
+	/// </summary>
+	/// <seealso href="https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/ucal_8h.html#a246d867677ec1a02775072aa0b5b018a"/>
 	public enum USystemTimeZoneType
 	{
+		/// <summary>Any system zones.</summary>
 		Any,
+		/// <summary>Canonical system zones.</summary>
 		Canonical,
+		/// <summary>Canonical system zones associated with actual locations.</summary>
 		CanonicalLocation,
 	}
 }

source/icu.net/Transliterator.cs

@@ -8,11 +8,29 @@
 
 namespace Icu
 {
+	/// <summary>
+	/// Wraps ICU's transliteration engine, which converts text from one script or encoding to another.
+	/// </summary>
 	public class Transliterator : IDisposable
 	{
+		/// <summary>
+		/// Direction constant indicating the direction in a transliterator, e.g., the forward or
+		/// reverse rules of a RuleBasedTransliterator.
+		/// </summary>
+		/// <seealso href="https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/utrans_8h.html#a04f480e9e8e40f0d8067521668dc06ec"/>
 		public enum UTransDirection
 		{
+			/// <summary>
+			/// Transliterates from &lt;source&gt; to &lt;target&gt; for a transliterator with ID
+			/// &lt;source&gt;-&lt;target&gt;. For a transliterator opened using a rule, means
+			/// forward direction rules, e.g., <c>A &gt; B</c>.
+			/// </summary>
 			Forward,
+			/// <summary>
+			/// Transliterates from &lt;target&gt; to &lt;source&gt; for a transliterator with ID
+			/// &lt;source&gt;-&lt;target&gt;. For a transliterator opened using a rule, means
+			/// reverse direction rules, e.g., <c>A &lt; B</c>.
+			/// </summary>
 			Reverse
 		}
 
@@ -289,7 +307,7 @@ private Transliterator(SafeTransliteratorHandle handle)
 		/// Transliterate <paramref name="text"/>.
 		/// </summary>
 		/// <param name="text">The text to transliterate</param>
-		/// <<param name="textCapacityMultiplier">The capacity for the buffer that holds the
+		/// <param name="textCapacityMultiplier">The capacity for the buffer that holds the
 		/// transliterated text, expressed as a multiplier of the text length.</param>
 		/// <returns>
 		/// The transliterated text. If the initial buffer overflows, the method retries with a doubled buffer.
@@ -343,6 +361,8 @@ public string Transliterate(string text, int textCapacityMultiplier = 3)
 		}
 
 		#region Disposable pattern
+		/// <summary>Releases the resources used by Transliterator.</summary>
+		/// <param name="disposing"><c>true</c> if called from <see cref="Dispose()"/>; <c>false</c> if called during finalization.</param>
 		protected virtual void Dispose(bool disposing)
 		{
 			if (disposing)
@@ -351,6 +371,7 @@ protected virtual void Dispose(bool disposing)
 			}
 		}
 
+		/// <inheritdoc/>
 		public void Dispose()
 		{
 			Dispose(true);

source/icu.net/icu.net.csproj

@@ -4,6 +4,9 @@
     <AssemblyName>icu.net</AssemblyName>
     <Description>icu.net is a C# Wrapper around ICU4C</Description>
     <PackageReadmeFile>README.md</PackageReadmeFile>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <NoWarn>$(NoWarn);CS1573</NoWarn>
+    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.xml</AllowedOutputExtensionsInPackageBuildOutputFolder>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="GitVersion.MsBuild" Version="6.0.5" PrivateAssets="all" />