diff --git a/src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs b/src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs new file mode 100644 index 000000000000..3224d9619f5a --- /dev/null +++ b/src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs @@ -0,0 +1,50 @@ +namespace Microsoft.Macios.Generator.Emitters; + +/// +/// 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. +/// +public static class Documentation { + + /// + /// Smart enum documentation. + /// + public static class SmartEnum { + + public static string ClassDocumentation (string name) => +@$"/// +/// Extension methods for the enumeration. +/// "; + + public static string GetConstant () => +@"/// +/// Retrieves the constant that describes . +/// +/// The instance on which this method operates."; + + public static string GetValueNSString (string name) => +@$"/// +/// Retrieves the value named by . +/// +/// The name of the constant to retrieve."; + + public static string GetValueHandle (string name) => +@$"/// +/// Retrieves the value represented by the backing field value in . +/// +/// The native handle with the name of the constant to retrieve."; + + public static string ToConstantArray (string name) => +@$"/// +/// Converts an array of enum values into an array of their corresponding constants. +/// +/// The array of enum values to convert."; + + public static string ToEnumArray (string _) => +@"/// +/// Converts an array of values into an array of their corresponding enum values. +/// +/// The array if values to convert."; + + } +} diff --git a/src/rgen/Microsoft.Macios.Generator/Emitters/EnumEmitter.cs b/src/rgen/Microsoft.Macios.Generator/Emitters/EnumEmitter.cs index b7a9045c4a56..ec046318efa0 100644 --- a/src/rgen/Microsoft.Macios.Generator/Emitters/EnumEmitter.cs +++ b/src/rgen/Microsoft.Macios.Generator/Emitters/EnumEmitter.cs @@ -54,7 +54,7 @@ bool TryEmit (TabbedWriter classBlock, in Binding binding) return true; } - void EmitExtensionMethods (TabbedWriter classBlock, in Binding binding) + void EmitExtensionMethods (TabbedWriter classBlock, string symbolName, in Binding binding) { if (binding.EnumMembers.Length == 0) return; @@ -62,6 +62,7 @@ void EmitExtensionMethods (TabbedWriter classBlock, in Binding bin // 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)) { @@ -81,6 +82,7 @@ void EmitExtensionMethods (TabbedWriter 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));"); @@ -98,6 +100,7 @@ void EmitExtensionMethods (TabbedWriter 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)) { @@ -109,6 +112,7 @@ void EmitExtensionMethods (TabbedWriter classBlock, in Binding bin classBlock.WriteLine (); // To ConstantArray + classBlock.WriteDocumentation (Documentation.SmartEnum.ToConstantArray (symbolName)); classBlock.WriteRaw ( @$"internal static NSString?[]? ToConstantArray (this {binding.Name}[]? values) {{ @@ -124,6 +128,7 @@ void EmitExtensionMethods (TabbedWriter 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) {{ @@ -155,10 +160,13 @@ public bool TryEmit (in BindingContext bindingContext, [NotNullWhen (false)] out 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}];"); @@ -171,7 +179,7 @@ public bool TryEmit (in BindingContext bindingContext, [NotNullWhen (false)] out 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 (); } diff --git a/src/rgen/Microsoft.Macios.Generator/IO/TabbedWriter.cs b/src/rgen/Microsoft.Macios.Generator/IO/TabbedWriter.cs index 0251ef289200..39bf5fa9ea15 100644 --- a/src/rgen/Microsoft.Macios.Generator/IO/TabbedWriter.cs +++ b/src/rgen/Microsoft.Macios.Generator/IO/TabbedWriter.cs @@ -227,6 +227,20 @@ public TabbedWriter WriteRaw (string rawString) } #endif + /// + /// 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. + /// + /// The documentation raw string. + /// The current writer. + public TabbedWriter WriteDocumentation (string docsRawString) + { + // user the raw string to write the documentation and add a new line + WriteRaw (docsRawString); + WriteLine (); + return this; + } + /// /// Append a new raw literal by prepending the correct indentation. /// diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureDeviceTypeEnum.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureDeviceTypeEnum.cs index 9b95aedb6cb6..053fef129209 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureDeviceTypeEnum.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureDeviceTypeEnum.cs @@ -9,6 +9,9 @@ namespace AVFoundation; +/// +/// Extension methods for the enumeration. +/// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] public static partial class AVCaptureDeviceTypeExtensions { @@ -125,6 +128,10 @@ internal unsafe static IntPtr AVCaptureDeviceTypeBuiltInLiDARDepthCamera } } + /// + /// Retrieves the constant that describes . + /// + /// The instance on which this method operates. 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); } + /// + /// Retrieves the value named by . + /// + /// The name of the constant to retrieve. 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."); } + /// + /// Retrieves the value represented by the backing field value in . + /// + /// The native handle with the name of the constant to retrieve. public static AVCaptureDeviceType GetValue (NativeHandle handle) { using var str = Runtime.GetNSObject (handle)!; return GetValue (str); } + /// + /// Converts an array of enum values into an array of their corresponding constants. + /// + /// The array of enum values to convert. internal static NSString?[]? ToConstantArray (this AVCaptureDeviceType[]? values) { if (values is null) @@ -214,6 +233,10 @@ public static AVCaptureDeviceType GetValue (NativeHandle handle) return rv.ToArray (); } + /// + /// Converts an array of values into an array of their corresponding enum values. + /// + /// The array if values to convert. internal static AVCaptureDeviceType[]? ToEnumArray (this NSString[]? values) { if (values is null) diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureSystemPressureLevel.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureSystemPressureLevel.cs index ac2fbd36ea24..f4f394fd579f 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureSystemPressureLevel.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedAVCaptureSystemPressureLevel.cs @@ -9,6 +9,9 @@ namespace AVFoundation; +/// +/// Extension methods for the enumeration. +/// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] public static partial class AVCaptureSystemPressureLevelExtensions { @@ -65,6 +68,10 @@ internal unsafe static IntPtr AVCaptureSystemPressureLevelShutdown } } + /// + /// Retrieves the constant that describes . + /// + /// The instance on which this method operates. 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); } + /// + /// Retrieves the value named by . + /// + /// The name of the constant to retrieve. 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."); } + /// + /// Retrieves the value represented by the backing field value in . + /// + /// The native handle with the name of the constant to retrieve. public static AVCaptureSystemPressureLevel GetValue (NativeHandle handle) { using var str = Runtime.GetNSObject (handle)!; return GetValue (str); } + /// + /// Converts an array of enum values into an array of their corresponding constants. + /// + /// The array of enum values to convert. internal static NSString?[]? ToConstantArray (this AVCaptureSystemPressureLevel[]? values) { if (values is null) @@ -124,6 +143,10 @@ public static AVCaptureSystemPressureLevel GetValue (NativeHandle handle) return rv.ToArray (); } + /// + /// Converts an array of values into an array of their corresponding enum values. + /// + /// The array if values to convert. internal static AVCaptureSystemPressureLevel[]? ToEnumArray (this NSString[]? values) { if (values is null) diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnum.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnum.cs index a83e39472891..d76d7ca76c80 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnum.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnum.cs @@ -10,6 +10,9 @@ namespace CustomLibrary; +/// +/// Extension methods for the enumeration. +/// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] public static partial class CustomLibraryEnumExtensions { @@ -46,6 +49,10 @@ internal unsafe static IntPtr High } } + /// + /// Retrieves the constant that describes . + /// + /// The instance on which this method operates. 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); } + /// + /// Retrieves the value named by . + /// + /// The name of the constant to retrieve. 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."); } + /// + /// Retrieves the value represented by the backing field value in . + /// + /// The native handle with the name of the constant to retrieve. public static CustomLibraryEnum GetValue (NativeHandle handle) { using var str = Runtime.GetNSObject (handle)!; return GetValue (str); } + /// + /// Converts an array of enum values into an array of their corresponding constants. + /// + /// The array of enum values to convert. internal static NSString?[]? ToConstantArray (this CustomLibraryEnum[]? values) { if (values is null) @@ -95,6 +114,10 @@ public static CustomLibraryEnum GetValue (NativeHandle handle) return rv.ToArray (); } + /// + /// Converts an array of values into an array of their corresponding enum values. + /// + /// The array if values to convert. internal static CustomLibraryEnum[]? ToEnumArray (this NSString[]? values) { if (values is null) diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnumInternal.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnumInternal.cs index 920ad2db2dff..0208d212e14f 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnumInternal.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedCustomLibraryEnumInternal.cs @@ -10,6 +10,9 @@ namespace CustomLibrary; +/// +/// Extension methods for the enumeration. +/// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] public static partial class CustomLibraryEnumInternalExtensions { @@ -46,6 +49,10 @@ internal unsafe static IntPtr High } } + /// + /// Retrieves the constant that describes . + /// + /// The instance on which this method operates. public static NSString? GetConstant (this CustomLibraryEnumInternal self) { IntPtr ptr = IntPtr.Zero; @@ -64,6 +71,10 @@ internal unsafe static IntPtr High return (NSString?) Runtime.GetNSObject (ptr); } + /// + /// Retrieves the value named by . + /// + /// The name of the constant to retrieve. public static CustomLibraryEnumInternal GetValue (NSString constant) { if (constant is null) @@ -77,12 +88,20 @@ public static CustomLibraryEnumInternal GetValue (NSString constant) throw new NotSupportedException ($"The constant {constant} has no associated enum value on this platform."); } + /// + /// Retrieves the value represented by the backing field value in . + /// + /// The native handle with the name of the constant to retrieve. public static CustomLibraryEnumInternal GetValue (NativeHandle handle) { using var str = Runtime.GetNSObject (handle)!; return GetValue (str); } + /// + /// Converts an array of enum values into an array of their corresponding constants. + /// + /// The array of enum values to convert. internal static NSString?[]? ToConstantArray (this CustomLibraryEnumInternal[]? values) { if (values is null) @@ -95,6 +114,10 @@ public static CustomLibraryEnumInternal GetValue (NativeHandle handle) return rv.ToArray (); } + /// + /// Converts an array of values into an array of their corresponding enum values. + /// + /// The array if values to convert. internal static CustomLibraryEnumInternal[]? ToEnumArray (this NSString[]? values) { if (values is null) diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedMacOSAVMediaCharacteristics.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedMacOSAVMediaCharacteristics.cs index e63fd2e585a9..aeb5497653d5 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedMacOSAVMediaCharacteristics.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectedMacOSAVMediaCharacteristics.cs @@ -10,6 +10,9 @@ namespace AVFoundation; +/// +/// Extension methods for the enumeration. +/// [SupportedOSPlatform ("macos")] [SupportedOSPlatform ("ios11.0")] [SupportedOSPlatform ("tvos11.0")] @@ -258,6 +261,10 @@ internal unsafe static IntPtr AVMediaCharacteristicContainsAlphaChannel } } + /// + /// Retrieves the constant that describes . + /// + /// The instance on which this method operates. public static NSString? GetConstant (this AVMediaCharacteristics self) { IntPtr ptr = IntPtr.Zero; @@ -318,6 +325,10 @@ internal unsafe static IntPtr AVMediaCharacteristicContainsAlphaChannel return (NSString?) Runtime.GetNSObject (ptr); } + /// + /// Retrieves the value named by . + /// + /// The name of the constant to retrieve. public static AVMediaCharacteristics GetValue (NSString constant) { if (constant is null) @@ -359,12 +370,20 @@ public static AVMediaCharacteristics GetValue (NSString constant) throw new NotSupportedException ($"The constant {constant} has no associated enum value on this platform."); } + /// + /// Retrieves the value represented by the backing field value in . + /// + /// The native handle with the name of the constant to retrieve. public static AVMediaCharacteristics GetValue (NativeHandle handle) { using var str = Runtime.GetNSObject (handle)!; return GetValue (str); } + /// + /// Converts an array of enum values into an array of their corresponding constants. + /// + /// The array of enum values to convert. internal static NSString?[]? ToConstantArray (this AVMediaCharacteristics[]? values) { if (values is null) @@ -377,6 +396,10 @@ public static AVMediaCharacteristics GetValue (NativeHandle handle) return rv.ToArray (); } + /// + /// Converts an array of values into an array of their corresponding enum values. + /// + /// The array if values to convert. internal static AVMediaCharacteristics[]? ToEnumArray (this NSString[]? values) { if (values is null) diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectediOSAVMediaCharacteristics.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectediOSAVMediaCharacteristics.cs index 58c1903347d0..a856c0e0eb55 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectediOSAVMediaCharacteristics.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/SmartEnum/Data/ExpectediOSAVMediaCharacteristics.cs @@ -10,6 +10,9 @@ namespace AVFoundation; +/// +/// Extension methods for the enumeration. +/// [SupportedOSPlatform ("macos")] [SupportedOSPlatform ("ios11.0")] [SupportedOSPlatform ("tvos11.0")] @@ -272,6 +275,10 @@ internal unsafe static IntPtr AVMediaCharacteristicContainsAlphaChannel } } + /// + /// Retrieves the constant that describes . + /// + /// The instance on which this method operates. public static NSString? GetConstant (this AVMediaCharacteristics self) { IntPtr ptr = IntPtr.Zero; @@ -335,6 +342,10 @@ internal unsafe static IntPtr AVMediaCharacteristicContainsAlphaChannel return (NSString?) Runtime.GetNSObject (ptr); } + /// + /// Retrieves the value named by . + /// + /// The name of the constant to retrieve. public static AVMediaCharacteristics GetValue (NSString constant) { if (constant is null) @@ -378,12 +389,20 @@ public static AVMediaCharacteristics GetValue (NSString constant) throw new NotSupportedException ($"The constant {constant} has no associated enum value on this platform."); } + /// + /// Retrieves the value represented by the backing field value in . + /// + /// The native handle with the name of the constant to retrieve. public static AVMediaCharacteristics GetValue (NativeHandle handle) { using var str = Runtime.GetNSObject (handle)!; return GetValue (str); } + /// + /// Converts an array of enum values into an array of their corresponding constants. + /// + /// The array of enum values to convert. internal static NSString?[]? ToConstantArray (this AVMediaCharacteristics[]? values) { if (values is null) @@ -396,6 +415,10 @@ public static AVMediaCharacteristics GetValue (NativeHandle handle) return rv.ToArray (); } + /// + /// Converts an array of values into an array of their corresponding enum values. + /// + /// The array if values to convert. internal static AVMediaCharacteristics[]? ToEnumArray (this NSString[]? values) { if (values is null)