[Foundation] Document and slightly simplify the NSObject.Dangerous[Re…

…tain|Release|Autorelease] methods. (#21844)

src/Foundation/NSObject2.cs

@@ -569,12 +569,17 @@ bool DynamicConformsToProtocol (NativeHandle protocol)
 			return false;
 		}
 
+		/// <summary>Calls the 'release' selector on this object.</summary>
 		[EditorBrowsable (EditorBrowsableState.Advanced)]
 		public void DangerousRelease ()
 		{
 			DangerousRelease (handle);
 		}
 
+		/// <summary>Calls the 'release' selector on an Objective-C object.</summary>
+		/// <param name="handle">The Objective-C object to release.</param>
+		/// <remarks>It's safe to call this function with <see cref="NativeHandle.Zero" />.</remarks>
+		[EditorBrowsable (EditorBrowsableState.Never)]
 		internal static void DangerousRelease (NativeHandle handle)
 		{
 			if (handle == IntPtr.Zero)
@@ -586,6 +591,10 @@ internal static void DangerousRelease (NativeHandle handle)
 #endif
 		}
 
+		/// <summary>Calls the 'retain' selector on an Objective-C object.</summary>
+		/// <param name="handle">The Objective-C object to retain.</param>
+		/// <remarks>It's safe to call this function with <see cref="NativeHandle.Zero" />.</remarks>
+		[EditorBrowsable (EditorBrowsableState.Never)]
 		internal static void DangerousRetain (NativeHandle handle)
 		{
 			if (handle == IntPtr.Zero)
@@ -597,6 +606,9 @@ internal static void DangerousRetain (NativeHandle handle)
 #endif
 		}
 
+		/// <summary>Calls the 'autorelease' selector on an Objective-C object.</summary>
+		/// <param name="handle">The Objective-C object to autorelease.</param>
+		/// <remarks>It's safe to call this function with <see cref="NativeHandle.Zero" />.</remarks>
 		internal static void DangerousAutorelease (NativeHandle handle)
 		{
 #if MONOMAC
@@ -606,25 +618,21 @@ internal static void DangerousAutorelease (NativeHandle handle)
 #endif
 		}
 
+		/// <summary>Calls the 'retain' selector on this object.</summary>
+		/// <returns>This object.</returns>
 		[EditorBrowsable (EditorBrowsableState.Advanced)]
 		public NSObject DangerousRetain ()
 		{
-#if MONOMAC
-			Messaging.void_objc_msgSend (handle, Selector.RetainHandle);
-#else
-			Messaging.void_objc_msgSend (handle, Selector.GetHandle (Selector.Retain));
-#endif
+			DangerousRetain (handle);
 			return this;
 		}
 
+		/// <summary>Calls the 'autorelease' selector on this object.</summary>
+		/// <returns>This object.</returns>
 		[EditorBrowsable (EditorBrowsableState.Advanced)]
 		public NSObject DangerousAutorelease ()
 		{
-#if MONOMAC
-			Messaging.void_objc_msgSend (handle, Selector.AutoreleaseHandle);
-#else
-			Messaging.void_objc_msgSend (handle, Selector.GetHandle (Selector.Autorelease));
-#endif
+			DangerousAutorelease (handle);
 			return this;
 		}
 

tests/cecil-tests/Documentation.KnownFailures.txt

@@ -33718,9 +33718,6 @@ M:Foundation.NSObject.Bind(Foundation.NSString,Foundation.NSObject,System.String
 M:Foundation.NSObject.CommitEditing
 M:Foundation.NSObject.CommitEditing(Foundation.NSObject,ObjCRuntime.Selector,System.IntPtr)
 M:Foundation.NSObject.ConformsToProtocol(ObjCRuntime.NativeHandle)
-M:Foundation.NSObject.DangerousAutorelease
-M:Foundation.NSObject.DangerousRelease
-M:Foundation.NSObject.DangerousRetain
 M:Foundation.NSObject.Dispose
 M:Foundation.NSObject.Dispose(System.Boolean)
 M:Foundation.NSObject.DoesNotRecognizeSelector(ObjCRuntime.Selector)