[RGen] Add docs to the SmartEnum generated methods. (#22268)

Add the documentation to the smart enum extension class and its methods.

Author: mandel-macaque

src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs

@@ -0,0 +1,50 @@
+namespace Microsoft.Macios.Generator.Emitters;
+
+/// <summary>
+/// Static class that holds all the documentation strings. This allows to make the code generator
+/// cleaner by removing the need to have the documentation strings in the code.
+/// </summary>
+public static class Documentation {
+
+	/// <summary>
+	/// Smart enum documentation.
+	/// </summary>
+	public static class SmartEnum {
+
+		public static string ClassDocumentation (string name) =>
+@$"/// <summary>
+/// Extension methods for the <see cref=""{name}"" /> enumeration.
+/// </summary>";
+
+		public static string GetConstant () =>
+@"/// <summary>
+/// Retrieves the <see cref=""global::Foundation.NSString"" /> constant that describes <paramref name=""self"" />.
+/// </summary>
+/// <param name=""self"">The instance on which this method operates.</param>";
+
+		public static string GetValueNSString (string name) =>
+@$"/// <summary>
+/// Retrieves the <see cref=""{name}"" /> value named by <paramref name=""constant"" />.
+/// </summary>
+/// <param name=""constant"">The name of the constant to retrieve.</param>";
+
+		public static string GetValueHandle (string name) =>
+@$"/// <summary>
+/// Retrieves the <see cref=""{name}"" /> value represented by the backing field value in <paramref name=""handle"" />.
+/// </summary>
+/// <param name=""handle"">The native handle with the name of the constant to retrieve.</param>";
+
+		public static string ToConstantArray (string name) =>
+@$"/// <summary>
+/// Converts an array of <see cref=""{name}"" /> enum values into an array of their corresponding constants.
+/// </summary>
+/// <param name=""values"">The array of enum values to convert.</param>";
+
+		public static string ToEnumArray (string _) =>
+@"/// <summary>
+/// Converts an array of <see cref=""NSString"" /> values into an array of their corresponding enum values.
+/// </summary>
+/// <param name=""values"">The array if <see cref=""NSString"" /> values to convert.</param>";
+
+	}
+}

src/rgen/Microsoft.Macios.Generator/Emitters/EnumEmitter.cs

@@ -57,14 +57,15 @@ bool TryEmit (TabbedWriter<StringWriter> classBlock, in Binding binding)
 		return true;
 	}
 
-	void EmitExtensionMethods (TabbedWriter<StringWriter> classBlock, in Binding binding)
+	void EmitExtensionMethods (TabbedWriter<StringWriter> classBlock, string symbolName, in Binding binding)
 	{
 		if (binding.EnumMembers.Length == 0)
 			return;
 
 		// smart enum require 4 diff methods to be able to retrieve the values
 
 		// Get constant
+		classBlock.WriteDocumentation (Documentation.SmartEnum.GetConstant ());
 		using (var getConstantBlock = classBlock.CreateBlock ($"public static NSString? GetConstant (this {binding.Name} self)", true)) {
 			getConstantBlock.WriteLine ("IntPtr ptr = IntPtr.Zero;");
 			using (var switchBlock = getConstantBlock.CreateBlock ("switch ((int) self)", true)) {
@@ -84,6 +85,7 @@ void EmitExtensionMethods (TabbedWriter<StringWriter> classBlock, in Binding bin
 
 		classBlock.WriteLine ();
 		// Get value
+		classBlock.WriteDocumentation (Documentation.SmartEnum.GetValueNSString (symbolName));
 		using (var getValueBlock = classBlock.CreateBlock ($"public static {binding.Name} GetValue (NSString constant)", true)) {
 			getValueBlock.WriteLine ("if (constant is null)");
 			getValueBlock.WriteLine ("\tthrow new ArgumentNullException (nameof (constant));");
@@ -101,6 +103,7 @@ void EmitExtensionMethods (TabbedWriter<StringWriter> classBlock, in Binding bin
 		classBlock.WriteLine ();
 
 		// get value from a handle, this is a helper method used in the BindAs bindings.
+		classBlock.WriteDocumentation (Documentation.SmartEnum.GetValueHandle (symbolName));
 		using (var getValueFromHandle =
 			   classBlock.CreateBlock ($"public static {binding.Name} GetValue (NativeHandle handle)",
 				   true)) {
@@ -112,6 +115,7 @@ void EmitExtensionMethods (TabbedWriter<StringWriter> classBlock, in Binding bin
 
 		classBlock.WriteLine ();
 		// To ConstantArray
+		classBlock.WriteDocumentation (Documentation.SmartEnum.ToConstantArray (symbolName));
 		classBlock.WriteRaw (
 @$"internal static NSString?[]? ToConstantArray (this {binding.Name}[]? values)
 {{
@@ -127,6 +131,7 @@ void EmitExtensionMethods (TabbedWriter<StringWriter> classBlock, in Binding bin
 		classBlock.WriteLine ();
 		classBlock.WriteLine ();
 		// ToEnumArray
+		classBlock.WriteDocumentation (Documentation.SmartEnum.ToEnumArray (symbolName));
 		classBlock.WriteRaw (
 @$"internal static {binding.Name}[]? ToEnumArray (this NSString[]? values)
 {{
@@ -165,10 +170,13 @@ bool TryEmitSmartEnum (in BindingTypeData<SmartEnum> _, in BindingContext bindin
 		bindingContext.Builder.WriteLine ($"namespace {string.Join (".", bindingContext.Changes.Namespace)};");
 		bindingContext.Builder.WriteLine ();
 
+		var symbolName = GetSymbolName (bindingContext.Changes);
+		var extensionClassDeclaration =
+			bindingContext.Changes.ToSmartEnumExtensionDeclaration (symbolName);
+
+		bindingContext.Builder.WriteDocumentation (Documentation.SmartEnum.ClassDocumentation (symbolName));
 		bindingContext.Builder.AppendMemberAvailability (bindingContext.Changes.SymbolAvailability);
 		bindingContext.Builder.AppendGeneratedCodeAttribute ();
-		var extensionClassDeclaration =
-			bindingContext.Changes.ToSmartEnumExtensionDeclaration (GetSymbolName (bindingContext.Changes));
 		using (var classBlock = bindingContext.Builder.CreateBlock (extensionClassDeclaration.ToString (), true)) {
 			classBlock.WriteLine ();
 			classBlock.WriteLine ($"static IntPtr[] values = new IntPtr [{bindingContext.Changes.EnumMembers.Length}];");
@@ -181,7 +189,7 @@ bool TryEmitSmartEnum (in BindingTypeData<SmartEnum> _, in BindingContext bindin
 			classBlock.WriteLine ();
 
 			// emit the extension methods that will be used to get the values from the enum
-			EmitExtensionMethods (classBlock, bindingContext.Changes);
+			EmitExtensionMethods (classBlock, symbolName, bindingContext.Changes);
 			classBlock.WriteLine ();
 		}
 

src/rgen/Microsoft.Macios.Generator/IO/TabbedWriter.cs

@@ -227,6 +227,20 @@ public TabbedWriter<T> WriteRaw (string rawString)
 	}
 #endif
 
+	/// <summary>
+	/// Writes a multi-line documentation comment. Ensure that the raw string used for the docs
+	/// does not have a new line at the end, this method will add it for you.
+	/// </summary>
+	/// <param name="docsRawString">The documentation raw string.</param>
+	/// <returns>The current writer.</returns>
+	public TabbedWriter<T> WriteDocumentation (string docsRawString)
+	{
+		// user the raw string to write the documentation and add a new line
+		WriteRaw (docsRawString);
+		WriteLine ();
+		return this;
+	}
+
 	/// <summary>
 	/// Append a new raw literal by prepending the correct indentation.
 	/// </summary>

tests/cecil-tests/Documentation.KnownFailures.txt

@@ -23148,9 +23148,6 @@ M:AVFoundation.AVCapturePhotoOutputReadinessCoordinator.Dispose(System.Boolean)
 M:AVFoundation.AVCapturePhotoSettings.Dispose(System.Boolean)
 M:AVFoundation.AVCapturePhotoSettingsThumbnailFormat.#ctor
 M:AVFoundation.AVCapturePhotoSettingsThumbnailFormat.#ctor(Foundation.NSDictionary)
-M:AVFoundation.AVCaptureReactionTypeExtensions.GetConstant(AVFoundation.AVCaptureReactionType)
-M:AVFoundation.AVCaptureReactionTypeExtensions.GetValue(Foundation.NSString)
-M:AVFoundation.AVCaptureReactionTypeExtensions.GetValue(ObjCRuntime.NativeHandle)
 M:AVFoundation.AVCaptureSessionRuntimeErrorEventArgs.#ctor(Foundation.NSNotification)
 M:AVFoundation.AVCaptureStillImageOutput.CaptureStillImageTaskAsync(AVFoundation.AVCaptureConnection)
 M:AVFoundation.AVCaptureVideoDataOutput.GetRecommendedVideoSettings(AVFoundation.AVVideoCodecType,AVFoundation.AVFileTypes,Foundation.NSUrl)
@@ -66092,7 +66089,6 @@ T:AVFoundation.AVCapturePrimaryConstituentDeviceRestrictedSwitchingBehaviorCondi
 T:AVFoundation.AVCapturePrimaryConstituentDeviceSwitchingBehavior
 T:AVFoundation.AVCaptureReactionType
 T:AVFoundation.AVCaptureReactionType_Extensions
-T:AVFoundation.AVCaptureReactionTypeExtensions
 T:AVFoundation.AVCaptureSessionControlsDelegate
 T:AVFoundation.AVCaptureSessionInterruptionReason
 T:AVFoundation.AVCaptureSessionRuntimeErrorEventArgs

tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureDeviceTypeEnum.cs

@@ -9,6 +9,9 @@
 
 namespace AVFoundation;
 
+/// <summary>
+/// Extension methods for the <see cref="AVCaptureDeviceTypeExtensions" /> enumeration.
+/// </summary>
 [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)]
 public static partial class AVCaptureDeviceTypeExtensions
 {
@@ -125,6 +128,10 @@ internal unsafe static IntPtr AVCaptureDeviceTypeBuiltInLiDARDepthCamera
 		}
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="global::Foundation.NSString" /> constant that describes <paramref name="self" />.
+	/// </summary>
+	/// <param name="self">The instance on which this method operates.</param>
 	public static NSString? GetConstant (this AVCaptureDeviceType self)
 	{
 		IntPtr ptr = IntPtr.Zero;
@@ -167,6 +174,10 @@ internal unsafe static IntPtr AVCaptureDeviceTypeBuiltInLiDARDepthCamera
 		return (NSString?) Runtime.GetNSObject (ptr);
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="AVCaptureDeviceTypeExtensions" /> value named by <paramref name="constant" />.
+	/// </summary>
+	/// <param name="constant">The name of the constant to retrieve.</param>
 	public static AVCaptureDeviceType GetValue (NSString constant)
 	{
 		if (constant is null)
@@ -196,12 +207,20 @@ public static AVCaptureDeviceType GetValue (NSString constant)
 		throw new NotSupportedException ($"The constant {constant} has no associated enum value on this platform.");
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="AVCaptureDeviceTypeExtensions" /> value represented by the backing field value in <paramref name="handle" />.
+	/// </summary>
+	/// <param name="handle">The native handle with the name of the constant to retrieve.</param>
 	public static AVCaptureDeviceType GetValue (NativeHandle handle)
 	{
 		using var str = Runtime.GetNSObject<NSString> (handle)!;
 		return GetValue (str);
 	}
 
+	/// <summary>
+	/// Converts an array of <see cref="AVCaptureDeviceTypeExtensions" /> enum values into an array of their corresponding constants.
+	/// </summary>
+	/// <param name="values">The array of enum values to convert.</param>
 	internal static NSString?[]? ToConstantArray (this AVCaptureDeviceType[]? values)
 	{
 		if (values is null)
@@ -214,6 +233,10 @@ public static AVCaptureDeviceType GetValue (NativeHandle handle)
 		return rv.ToArray ();
 	}
 
+	/// <summary>
+	/// Converts an array of <see cref="NSString" /> values into an array of their corresponding enum values.
+	/// </summary>
+	/// <param name="values">The array if <see cref="NSString" /> values to convert.</param>
 	internal static AVCaptureDeviceType[]? ToEnumArray (this NSString[]? values)
 	{
 		if (values is null)

tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureSystemPressureLevel.cs

@@ -9,6 +9,9 @@
 
 namespace AVFoundation;
 
+/// <summary>
+/// Extension methods for the <see cref="AVCaptureSystemPressureLevelExtensions" /> enumeration.
+/// </summary>
 [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)]
 public static partial class AVCaptureSystemPressureLevelExtensions
 {
@@ -65,6 +68,10 @@ internal unsafe static IntPtr AVCaptureSystemPressureLevelShutdown
 		}
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="global::Foundation.NSString" /> constant that describes <paramref name="self" />.
+	/// </summary>
+	/// <param name="self">The instance on which this method operates.</param>
 	public static NSString? GetConstant (this AVCaptureSystemPressureLevel self)
 	{
 		IntPtr ptr = IntPtr.Zero;
@@ -89,6 +96,10 @@ internal unsafe static IntPtr AVCaptureSystemPressureLevelShutdown
 		return (NSString?) Runtime.GetNSObject (ptr);
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="AVCaptureSystemPressureLevelExtensions" /> value named by <paramref name="constant" />.
+	/// </summary>
+	/// <param name="constant">The name of the constant to retrieve.</param>
 	public static AVCaptureSystemPressureLevel GetValue (NSString constant)
 	{
 		if (constant is null)
@@ -106,12 +117,20 @@ public static AVCaptureSystemPressureLevel GetValue (NSString constant)
 		throw new NotSupportedException ($"The constant {constant} has no associated enum value on this platform.");
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="AVCaptureSystemPressureLevelExtensions" /> value represented by the backing field value in <paramref name="handle" />.
+	/// </summary>
+	/// <param name="handle">The native handle with the name of the constant to retrieve.</param>
 	public static AVCaptureSystemPressureLevel GetValue (NativeHandle handle)
 	{
 		using var str = Runtime.GetNSObject<NSString> (handle)!;
 		return GetValue (str);
 	}
 
+	/// <summary>
+	/// Converts an array of <see cref="AVCaptureSystemPressureLevelExtensions" /> enum values into an array of their corresponding constants.
+	/// </summary>
+	/// <param name="values">The array of enum values to convert.</param>
 	internal static NSString?[]? ToConstantArray (this AVCaptureSystemPressureLevel[]? values)
 	{
 		if (values is null)
@@ -124,6 +143,10 @@ public static AVCaptureSystemPressureLevel GetValue (NativeHandle handle)
 		return rv.ToArray ();
 	}
 
+	/// <summary>
+	/// Converts an array of <see cref="NSString" /> values into an array of their corresponding enum values.
+	/// </summary>
+	/// <param name="values">The array if <see cref="NSString" /> values to convert.</param>
 	internal static AVCaptureSystemPressureLevel[]? ToEnumArray (this NSString[]? values)
 	{
 		if (values is null)

tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnum.cs

@@ -10,6 +10,9 @@
 
 namespace CustomLibrary;
 
+/// <summary>
+/// Extension methods for the <see cref="CustomLibraryEnumExtensions" /> enumeration.
+/// </summary>
 [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)]
 public static partial class CustomLibraryEnumExtensions
 {
@@ -46,6 +49,10 @@ internal unsafe static IntPtr High
 		}
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="global::Foundation.NSString" /> constant that describes <paramref name="self" />.
+	/// </summary>
+	/// <param name="self">The instance on which this method operates.</param>
 	public static NSString? GetConstant (this CustomLibraryEnum self)
 	{
 		IntPtr ptr = IntPtr.Zero;
@@ -64,6 +71,10 @@ internal unsafe static IntPtr High
 		return (NSString?) Runtime.GetNSObject (ptr);
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="CustomLibraryEnumExtensions" /> value named by <paramref name="constant" />.
+	/// </summary>
+	/// <param name="constant">The name of the constant to retrieve.</param>
 	public static CustomLibraryEnum GetValue (NSString constant)
 	{
 		if (constant is null)
@@ -77,12 +88,20 @@ public static CustomLibraryEnum GetValue (NSString constant)
 		throw new NotSupportedException ($"The constant {constant} has no associated enum value on this platform.");
 	}
 
+	/// <summary>
+	/// Retrieves the <see cref="CustomLibraryEnumExtensions" /> value represented by the backing field value in <paramref name="handle" />.
+	/// </summary>
+	/// <param name="handle">The native handle with the name of the constant to retrieve.</param>
 	public static CustomLibraryEnum GetValue (NativeHandle handle)
 	{
 		using var str = Runtime.GetNSObject<NSString> (handle)!;
 		return GetValue (str);
 	}
 
+	/// <summary>
+	/// Converts an array of <see cref="CustomLibraryEnumExtensions" /> enum values into an array of their corresponding constants.
+	/// </summary>
+	/// <param name="values">The array of enum values to convert.</param>
 	internal static NSString?[]? ToConstantArray (this CustomLibraryEnum[]? values)
 	{
 		if (values is null)
@@ -95,6 +114,10 @@ public static CustomLibraryEnum GetValue (NativeHandle handle)
 		return rv.ToArray ();
 	}
 
+	/// <summary>
+	/// Converts an array of <see cref="NSString" /> values into an array of their corresponding enum values.
+	/// </summary>
+	/// <param name="values">The array if <see cref="NSString" /> values to convert.</param>
 	internal static CustomLibraryEnum[]? ToEnumArray (this NSString[]? values)
 	{
 		if (values is null)