From 47bf6082cf7309b71afa9e290d905c5ba2bd834e Mon Sep 17 00:00:00 2001 From: Manuel de la Pena Date: Sun, 2 Mar 2025 20:42:44 -0500 Subject: [PATCH 1/2] [RGen] Add default constructors doc strings. Add the doc strings in the generated default constructors. --- .../Emitters/ClassEmitter.cs | 4 + .../Emitters/Documentation.cs | 83 +++++++++++++++++++ .../BindingSourceGeneratorGeneratorTests.cs | 60 ++++++++++++++ .../ExpectedAVAudioPcmBufferDefaultCtr.cs | 61 ++++++++++++++ .../ExpectedAVAudioPcmBufferNoDefaultCtr.cs | 60 ++++++++++++++ .../ExpectedAVAudioPcmBufferNoNativeName.cs | 60 ++++++++++++++ .../Data/ExpectedAppKitPropertyTests.cs | 61 ++++++++++++++ .../Classes/Data/ExpectedCIImage.cs | 61 ++++++++++++++ .../ExpectedThreadSafeAppKitPropertyTests.cs | 61 ++++++++++++++ .../ExpectedThreadSafeUIKitPropertyTests.cs | 61 ++++++++++++++ .../Data/ExpectedUIKitPropertyTests.cs | 61 ++++++++++++++ .../Classes/Data/iOSExpectedPropertyTests.cs | 61 ++++++++++++++ .../Data/macOSExpectedPropertyTests.cs | 61 ++++++++++++++ .../Classes/Data/tvOSExpectedPropertyTests.cs | 61 ++++++++++++++ 14 files changed, 816 insertions(+) diff --git a/src/rgen/Microsoft.Macios.Generator/Emitters/ClassEmitter.cs b/src/rgen/Microsoft.Macios.Generator/Emitters/ClassEmitter.cs index 0b9c11a71e8d..ed901a681028 100644 --- a/src/rgen/Microsoft.Macios.Generator/Emitters/ClassEmitter.cs +++ b/src/rgen/Microsoft.Macios.Generator/Emitters/ClassEmitter.cs @@ -40,6 +40,7 @@ void EmitDefaultConstructors (in BindingContext bindingContext, TabbedWriter {ClassPtr};"); classBlock.WriteLine (); diff --git a/src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs b/src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs index 3224d9619f5a..f6214d5b15c1 100644 --- a/src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs +++ b/src/rgen/Microsoft.Macios.Generator/Emitters/Documentation.cs @@ -47,4 +47,87 @@ public static string ToEnumArray (string _) => /// The array if values to convert."; } + + /// + /// Doc string for the generated classes. + /// + public static class Class { + public static string ClassHandle (string _) => +@"/// The Objective-C class handle for this class. +/// The pointer to the Objective-C class. +/// +/// Each managed class mirrors an unmanaged Objective-C class. +/// This value contains the pointer to the Objective-C class. +/// It is similar to calling the managed or the native objc_getClass method with the type name. +/// "; + + public static string DefaultInit (string name) => +@$"/// Creates a new ', '}')}"" /> with default values."; + + public static string DefaultInitWithCode (string _) => +@"/// A constructor that initializes the object from the data stored in the unarchiver object. +/// The unarchiver object. +/// +/// This constructor is provided to allow the class to be initialized from an unarchiver (for example, during NIB deserialization). This is part of the protocol. +/// If developers want to create a subclass of this object and continue to support deserialization from an archive, they should implement a constructor with an identical signature: taking a single parameter of type and decorate it with the [Export(\""initWithCoder:\""] attribute. +/// The state of this object can also be serialized by using the companion method. +/// "; + + public static string DefaultInitWithFlag (string _) => +@"/// Constructor to call on derived classes to skip initialization and merely allocate the object. +/// Unused sentinel value, pass NSObjectFlag.Empty. +/// +/// +/// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . +/// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. +/// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. +/// The actual initialization of the object is up to the developer. +/// +/// +/// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. +/// Once the allocation has taken place, the constructor has to initialize the object. +/// With constructors generated by the binding generator this means that it manually invokes one of the ""init"" methods to initialize the object. +/// +/// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. +/// +/// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. +/// If this is not the case, developers should instead chain to the proper constructor in their class. +/// +/// +/// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. +/// Typically the chaining would look like this: +/// +/// +/// +/// +/// "; + + public static string DefaultInitWithHandle (string name) => +@"/// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. +/// Pointer (handle) to the unmanaged object. +/// +/// +/// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. +/// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. +/// +/// "; + } } diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/BindingSourceGeneratorGeneratorTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/BindingSourceGeneratorGeneratorTests.cs index 02f86ded0ad9..d5cd67fc5fe1 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/BindingSourceGeneratorGeneratorTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/BindingSourceGeneratorGeneratorTests.cs @@ -47,12 +47,72 @@ public partial class AVAudioPcmBuffer [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle (""AVAudioPCMBuffer""); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the ""init"" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected AVAudioPcmBuffer (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal AVAudioPcmBuffer (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferDefaultCtr.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferDefaultCtr.cs index 39ddeb9d0972..270b960b9127 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferDefaultCtr.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferDefaultCtr.cs @@ -22,8 +22,16 @@ public partial class AVAudioPcmBuffer [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("AVAudioPCMBuffer"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -35,10 +43,63 @@ public AVAudioPcmBuffer () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected AVAudioPcmBuffer (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal AVAudioPcmBuffer (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoDefaultCtr.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoDefaultCtr.cs index 483f31028ec5..22e7399d2a46 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoDefaultCtr.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoDefaultCtr.cs @@ -22,12 +22,72 @@ public partial class AVAudioPcmBuffer [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("AVAudioPCMBuffer"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected AVAudioPcmBuffer (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal AVAudioPcmBuffer (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoNativeName.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoNativeName.cs index 087cbe392a93..cc8317e79aa4 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoNativeName.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAVAudioPcmBufferNoNativeName.cs @@ -22,12 +22,72 @@ public partial class AVAudioPcmBuffer [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("AVAudioPcmBuffer"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected AVAudioPcmBuffer (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal AVAudioPcmBuffer (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAppKitPropertyTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAppKitPropertyTests.cs index 8fab29dad37a..889efddee9a5 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAppKitPropertyTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedAppKitPropertyTests.cs @@ -26,8 +26,16 @@ public partial class AppKitPropertyTests [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("AppKitPropertyTests"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -39,10 +47,63 @@ public AppKitPropertyTests () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected AppKitPropertyTests (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal AppKitPropertyTests (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedCIImage.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedCIImage.cs index 2f6836ea42e3..dd1e5d0351d8 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedCIImage.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedCIImage.cs @@ -22,8 +22,16 @@ public partial class CIImage [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("CIImage"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -35,10 +43,63 @@ public CIImage () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected CIImage (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal CIImage (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeAppKitPropertyTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeAppKitPropertyTests.cs index 041626ff8b4b..0fd4d33e273f 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeAppKitPropertyTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeAppKitPropertyTests.cs @@ -26,8 +26,16 @@ public partial class ThreadSafeAppKitPropertyTests [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("ThreadSafeAppKitPropertyTests"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -39,10 +47,63 @@ public ThreadSafeAppKitPropertyTests () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected ThreadSafeAppKitPropertyTests (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal ThreadSafeAppKitPropertyTests (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeUIKitPropertyTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeUIKitPropertyTests.cs index 1f5400f95ffa..fa40684155a3 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeUIKitPropertyTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedThreadSafeUIKitPropertyTests.cs @@ -26,8 +26,16 @@ public partial class ThreadSafeUIKitPropertyTests [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("ThreadSafeUIKitPropertyTests"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -39,10 +47,63 @@ public ThreadSafeUIKitPropertyTests () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected ThreadSafeUIKitPropertyTests (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal ThreadSafeUIKitPropertyTests (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedUIKitPropertyTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedUIKitPropertyTests.cs index db78ecfa19f4..b29095032855 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedUIKitPropertyTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedUIKitPropertyTests.cs @@ -26,8 +26,16 @@ public partial class UIKitPropertyTests [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("UIKitPropertyTests"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -39,10 +47,63 @@ public UIKitPropertyTests () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected UIKitPropertyTests (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal UIKitPropertyTests (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/iOSExpectedPropertyTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/iOSExpectedPropertyTests.cs index 1441ec32c0ba..d54cacd4de3d 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/iOSExpectedPropertyTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/iOSExpectedPropertyTests.cs @@ -115,8 +115,16 @@ public partial class PropertyTests [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("PropertyTests"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -128,10 +136,63 @@ public PropertyTests () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected PropertyTests (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal PropertyTests (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/macOSExpectedPropertyTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/macOSExpectedPropertyTests.cs index a082e6b01054..755322868b80 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/macOSExpectedPropertyTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/macOSExpectedPropertyTests.cs @@ -115,8 +115,16 @@ public partial class PropertyTests [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("PropertyTests"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -128,10 +136,63 @@ public PropertyTests () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected PropertyTests (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal PropertyTests (NativeHandle handle) : base (handle) {} diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/tvOSExpectedPropertyTests.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/tvOSExpectedPropertyTests.cs index a082e6b01054..755322868b80 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/tvOSExpectedPropertyTests.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/tvOSExpectedPropertyTests.cs @@ -115,8 +115,16 @@ public partial class PropertyTests [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("PropertyTests"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -128,10 +136,63 @@ public PropertyTests () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected PropertyTests (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal PropertyTests (NativeHandle handle) : base (handle) {} From e053c05ae617d5a8f1508d2d351c01379ed77fdb Mon Sep 17 00:00:00 2001 From: Manuel de la Pena Date: Wed, 5 Mar 2025 15:57:13 -0500 Subject: [PATCH 2/2] Fix expectation for test. --- .../Classes/Data/ExpectedNSUserDefaults.cs | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedNSUserDefaults.cs b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedNSUserDefaults.cs index 4a6ddbfb4877..350232b93a9d 100644 --- a/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedNSUserDefaults.cs +++ b/tests/rgen/Microsoft.Macios.Generator.Tests/Classes/Data/ExpectedNSUserDefaults.cs @@ -22,8 +22,16 @@ public partial class NSUserDefaults [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] static readonly NativeHandle class_ptr = Class.GetHandle ("NSUserDefaults"); + /// The Objective-C class handle for this class. + /// The pointer to the Objective-C class. + /// + /// Each managed class mirrors an unmanaged Objective-C class. + /// This value contains the pointer to the Objective-C class. + /// It is similar to calling the managed or the native objc_getClass method with the type name. + /// public override NativeHandle ClassHandle => class_ptr; + /// Creates a new with default values. [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [DesignatedInitializer] [Export ("init")] @@ -35,10 +43,63 @@ public NSUserDefaults () : base (NSObjectFlag.Empty) InitializeHandle (global::ObjCRuntime.Messaging.IntPtr_objc_msgSendSuper (this.SuperHandle, global::ObjCRuntime.Selector.GetHandle ("init")), "init"); } + /// Constructor to call on derived classes to skip initialization and merely allocate the object. + /// Unused sentinel value, pass NSObjectFlag.Empty. + /// + /// + /// This constructor should be called by derived classes when they completely construct the object in managed code and merely want the runtime to allocate and initialize the . + /// This is required to implement the two-step initialization process that Objective-C uses, the first step is to perform the object allocation, the second step is to initialize the object. + /// When developers invoke this constructor, they take advantage of a direct path that goes all the way up to to merely allocate the object's memory and bind the Objective-C and C# objects together. + /// The actual initialization of the object is up to the developer. + /// + /// + /// This constructor is typically used by the binding generator to allocate the object, but prevent the actual initialization to take place. + /// Once the allocation has taken place, the constructor has to initialize the object. + /// With constructors generated by the binding generator this means that it manually invokes one of the "init" methods to initialize the object. + /// + /// It is the developer's responsibility to completely initialize the object if they chain up using this constructor chain. + /// + /// In general, if the developer's constructor invokes the corresponding base implementation, then it should also call an Objective-C init method. + /// If this is not the case, developers should instead chain to the proper constructor in their class. + /// + /// + /// The argument value is ignored and merely ensures that the only code that is executed is the construction phase is the basic allocation and runtime type registration. + /// Typically the chaining would look like this: + /// + /// + /// + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected NSUserDefaults (NSObjectFlag t) : base (t) {} + /// A constructor used when creating managed representations of unmanaged objects. Called by the runtime. + /// Pointer (handle) to the unmanaged object. + /// + /// + /// This constructor is invoked by the runtime infrastructure () to create a new managed representation for a pointer to an unmanaged Objective-C object. + /// Developers should not invoke this method directly, instead they should call as it will prevent two instances of a managed object pointing to the same native object. + /// + /// [BindingImpl (BindingImplOptions.GeneratedCode | BindingImplOptions.Optimizable)] [EditorBrowsable (EditorBrowsableState.Advanced)] protected internal NSUserDefaults (NativeHandle handle) : base (handle) {}