Merge remote-tracking branch 'origin/main' into dev/rolf/msbuild-sdkdevpath

Author: rolfbjarne

.github/agents/xml-doc-writer.md

@@ -0,0 +1,29 @@
+---
+name: xml-doc-writer
+description: Specialized agent for working with XML docs in C# source code.
+---
+
+## Role
+
+You are a specialized agent for writing XML docs in C# source code. Your job is to validate and improve existing XML docs, and also write XML docs.
+
+## When to Invoke
+
+- When asked to from the Copilot CLI.
+
+## Workflow
+
+Step 1: Gather required information
+
+Before invoking this skill, make sure to know exactly which C# API whose XML docs to work on.
+
+Step 2: Write XML docs
+
+* Add XML docs for public or protected members and types that don't have any docs.
+* Remove any XML docs that are exactly "To be added."
+* If there's an XML doc that is added with an include attribute, replace the include attribute with the contents from the included file instead. Also remove the inlined content from the included file, and if there's nothing left in the included file, remove that file completely.
+* Verify existing XML comments for language, grammar, consistency and correctness.
+* Create 'see cref' attributes whenever suitable.
+* Remove unnecessary whitespace between the triple-slash and the xml comment; but keep/fix correct indentation.
+* Correct indentation: each nesting level adds exactly 2 spaces of indentation.
+* Reorder any top-level XML elements to have the following order: summary, value, param, return, exception, remarks.

builds/Versions-MacCatalyst.plist.in

@@ -149,8 +149,6 @@
 	<key>Optimizations</key>
 	<dict>
 		<!-- The key is the value to be passed to mtouch. The string is a very short description. Any IDE UI should also point to the documentation for the optimizations. -->
-		<key>inline-intptr-size</key>
-		<string>Inline IntPtr.Size</string>
 		<key>inline-runtime-arch</key>
 		<string>Inline NSObject.IsDirectBinding</string>
 		<key>dead-code-elimination</key>

builds/Versions-iOS.plist.in

@@ -173,8 +173,6 @@
 	<key>Optimizations</key>
 	<dict>
 		<!-- The key is the value to be passed to mtouch. The string is a very short description. Any IDE UI should also point to the documentation for the optimizations. -->
-		<key>inline-intptr-size</key>
-		<string>Inline IntPtr.Size</string>
 		<key>inline-runtime-arch</key>
 		<string>Inline NSObject.IsDirectBinding</string>
 		<key>dead-code-elimination</key>

builds/Versions-macOS.plist.in

@@ -94,8 +94,6 @@
 	<key>Optimizations</key>
 	<dict>
 		<!-- The key is the value to be passed to mmp. The string is a very short description. Any IDE UI should also point to the documentation for the optimizations. -->
-		<key>inline-intptr-size</key>
-		<string>Inline IntPtr.Size</string>
 		<key>inline-runtime-arch</key>
 		<string>Inline Runtime.Arch</string>
 		<key>inline-isdirectbinding</key>

builds/Versions-tvOS.plist.in

@@ -123,8 +123,6 @@
 	<key>Optimizations</key>
 	<dict>
 		<!-- The key is the value to be passed to mtouch. The string is a very short description. Any IDE UI should also point to the documentation for the optimizations. -->
-		<key>inline-intptr-size</key>
-		<string>Inline IntPtr.Size</string>
 		<key>inline-runtime-arch</key>
 		<string>Inline NSObject.IsDirectBinding</string>
 		<key>dead-code-elimination</key>

docs/api/UIKit/UIActionSheet.xml

@@ -47,44 +47,6 @@ The default behavior can be overridden by passing `--optimize=[+|-]remove-uithre
 
 [1]: /dotnet/api/UIKit.UIApplication.EnsureUIThread
 
-## Inline IntPtr.Size
-
-Inlines the constant value of `IntPtr.Size` according to the target platform.
-
-This optimization will change the following type of code:
-
-```csharp
-if (IntPtr.Size == 8) {
-    Console.WriteLine ("64-bit platform");
-} else {
-    Console.WriteLine ("32-bit platform");
-}
-```
-
-into the following (when building for a 64-bit platform):
-
-```csharp
-if (8 == 8) {
-    Console.WriteLine ("64-bit platform");
-} else {
-    Console.WriteLine ("32-bit platform");
-}
-```
-
-This optimization requires the linker to be enabled, and is only applied to
-methods with the `[BindingImpl (BindingImplOptions.Optimizable)]` attribute.
-
-By default it's enabled if targeting a single architecture, or for the
-platform assembly (**Xamarin.iOS.dll**, **Xamarin.TVOS.dll**,
-**Xamarin.WatchOS.dll** or **Xamarin.Mac.dll**).
-
-If targeting multiple architectures, this optimization will create different
-assemblies for the 32-bit version and the 64-bit version of the app, and both
-versions will have to be included in the app, effectively increasing the final
-app size instead of decreasing it.
-
-The default behavior can be overridden by passing `--optimize=[+|-]inline-intptr-size` to mtouch/mmp.
-
 ## Inline NSObject.IsDirectBinding
 
 `NSObject.IsDirectBinding` is an instance property that determines whether a
@@ -254,24 +216,12 @@ the binding code for `NFCIso15693ReadMultipleBlocksConfiguration.Range`):
 NSRange ret;
 if (IsDirectBinding) {
     if (Runtime.Arch == Arch.DEVICE) {
-        if (IntPtr.Size == 8) {
-            ret = global::ObjCRuntime.Messaging.NSRange_objc_msgSend (this.Handle, Selector.GetHandle ("range"));
-        } else {
-            global::ObjCRuntime.Messaging.NSRange_objc_msgSend_stret (out ret, this.Handle, Selector.GetHandle ("range"));
-        }
-    } else if (IntPtr.Size == 8) {
         ret = global::ObjCRuntime.Messaging.NSRange_objc_msgSend (this.Handle, Selector.GetHandle ("range"));
     } else {
         ret = global::ObjCRuntime.Messaging.NSRange_objc_msgSend (this.Handle, Selector.GetHandle ("range"));
     }
 } else {
     if (Runtime.Arch == Arch.DEVICE) {
-        if (IntPtr.Size == 8) {
-            ret = global::ObjCRuntime.Messaging.NSRange_objc_msgSendSuper (this.SuperHandle, Selector.GetHandle ("range"));
-        } else {
-            global::ObjCRuntime.Messaging.NSRange_objc_msgSendSuper_stret (out ret, this.SuperHandle, Selector.GetHandle ("range"));
-        }
-    } else if (IntPtr.Size == 8) {
         ret = global::ObjCRuntime.Messaging.NSRange_objc_msgSendSuper (this.SuperHandle, Selector.GetHandle ("range"));
     } else {
         ret = global::ObjCRuntime.Messaging.NSRange_objc_msgSendSuper (this.SuperHandle, Selector.GetHandle ("range"));

docs/website/optimizations.md

@@ -259,12 +259,7 @@ public int? PlaneAlignment {
 			}
 		}
 
-		// TODO: kCVPixelBufferIOSurfacePropertiesKey
-#if !MONOMAC
-		// The presence of the IOSurfacePropertiesKey mandates the allocation via IOSurfaceProperty
-		/// <summary>If this key is set, this instructs CoreVideo to allocate the video buffers using the IOSurface.    This is required for some uses of pixel buffers.</summary>
-		///         <value>To be added.</value>
-		///         <remarks>To be added.</remarks>
+		/// <summary>If this key is set, this instructs CoreVideo to allocate the video buffers using the <see cref="IOSurface.IOSurface" />. This is required for some uses of pixel buffers.</summary>
 		public bool? AllocateWithIOSurface {
 			set {
 				if (value.HasValue && value.Value)
@@ -277,11 +272,9 @@ public bool? AllocateWithIOSurface {
 			}
 		}
 
-#if !__MACCATALYST__
+#if !__MACCATALYST__ && !__MACOS__
 		/// <summary>Indicates whether the pixel buffer is compatible with OpenGL for Embedded Systems contexts.</summary>
-		///         <value>
-		///         </value>
-		///         <remarks>The property uses constant kCVPixelBufferOpenGLESCompatibilityKey value to access the underlying dictionary.</remarks>
+		/// <remarks>The property uses the <c>kCVPixelBufferOpenGLESCompatibilityKey</c> constant to access the underlying dictionary.</remarks>
 		[SupportedOSPlatform ("ios")]
 		[UnsupportedOSPlatform ("maccatalyst")]
 		[UnsupportedOSPlatform ("macos")]
@@ -297,12 +290,6 @@ public bool? OpenGLESCompatibility {
 #endif
 
 		/// <summary>Indicates whether the pixel buffer is compatible with Metal.</summary>
-		///         <value>To be added.</value>
-		///         <remarks>To be added.</remarks>
-		[SupportedOSPlatform ("ios")]
-		[SupportedOSPlatform ("maccatalyst")]
-		[SupportedOSPlatform ("tvos")]
-		[UnsupportedOSPlatform ("macos")]
 		public bool? MetalCompatibility {
 			set {
 				SetBooleanValue (CVPixelBuffer.MetalCompatibilityKey, value);
@@ -311,7 +298,6 @@ public bool? MetalCompatibility {
 				return GetBoolValue (CVPixelBuffer.MetalCompatibilityKey);
 			}
 		}
-#endif
-#endif
+#endif // !COREBUILD
 	}
 }

src/CoreVideo/CVPixelBufferAttributes.cs

@@ -12,15 +12,53 @@
 
 using System.Collections;
 
-// Disable until we get around to enable + fix any issues.
-#nullable disable
+#nullable enable
 
 namespace UIKit {
+	/// <summary>A <see cref="UIView" /> that displays an action sheet with one or more buttons.</summary>
+	/// <remarks>
+	///   <para>Use <see cref="UIAlertController" /> rather than this class. Extensions may not use this class at all.</para>
+	///   <para>
+	///     The <see cref="UIActionSheet" /> control is a convenient way to allow the application user to choose among alternative actions.
+	///     The following code and diagram are taken from the "Action Sheets" section of the "iOS Standard Controls" sample.
+	///   </para>
+	///   <example>
+	///     <code lang="csharp lang-csharp"><![CDATA[
+	/// protected void HandleBtnActionSheetWithOtherButtonsTouchUpInside (object sender, EventArgs e)
+	/// {
+	/// 	actionSheet = new UIActionSheet ("action sheet with other buttons");
+	/// 	actionSheet.AddButton ("delete");
+	/// 	actionSheet.AddButton ("cancel");
+	/// 	actionSheet.AddButton ("a different option!");
+	/// 	actionSheet.AddButton ("another option");
+	/// 	actionSheet.DestructiveButtonIndex = 0;
+	/// 	actionSheet.CancelButtonIndex = 1;
+	/// 	//actionSheet.FirstOtherButtonIndex = 2;
+	/// 	actionSheet.Clicked += delegate(object a, UIButtonEventArgs b) {
+	/// 		Console.WriteLine ("Button " + b.ButtonIndex.ToString () + " clicked");
+	/// 	};
+	/// 	actionSheet.ShowInView (View);
+	/// }
+	/// ]]></code>
+	///   </example>
+	///   <para>
+	///     <img href="~/xml/UIKit/_images/UIKit.UIActionSheet.png" alt="Screenshot showing the UIActionSheet" />
+	///   </para>
+	/// </remarks>
 	public partial class UIActionSheet : IEnumerable {
 
-	/// <include file="../../docs/api/UIKit/UIActionSheet.xml" path="/Documentation/Docs[@DocId='M:UIKit.UIActionSheet.#ctor(System.String,UIKit.IUIActionSheetDelegate,System.String,System.String,System.String[])']/*" />
-	public UIActionSheet (string title, IUIActionSheetDelegate del, string cancelTitle, string destroy, params string [] other)
-			: this (title, del, null, null, (string) null)
+		/// <summary>Initializes a <see cref="UIActionSheet" /> instance.</summary>
+		/// <param name="title">A title to be displayed in the title area of the action sheet.</param>
+		/// <param name="del">A delegate that will respond to taps in the action sheet.</param>
+		/// <param name="cancelTitle">The title of the Cancel button. This will be displayed in a black button.</param>
+		/// <param name="destroy">The title of the destructive button. This will be displayed in a red button.</param>
+		/// <param name="other">An array of <see cref="string" /> to use for other buttons in the <see cref="UIActionSheet" />.</param>
+		/// <remarks>
+		///   <para>Pass <see langword="null" /> to <paramref name="title" /> if there is no text to display in the title area.</para>
+		///   <para>If the action sheet is being presented on an iPad, then the <paramref name="cancelTitle" /> should be set to <see langword="null" />.</para>
+		/// </remarks>
+		public UIActionSheet (string? title, IUIActionSheetDelegate? del, string? cancelTitle, string? destroy, params string? []? other)
+			: this (title, del, null, null, (string?) null)
 		{
 			if (destroy is not null)
 				DestructiveButtonIndex = AddButton (destroy);
@@ -31,7 +69,7 @@ public UIActionSheet (string title, IUIActionSheetDelegate del, string cancelTit
 				return;
 			}
 
-			foreach (string b in other) {
+			foreach (string? b in other) {
 				if (b is not null)
 					AddButton (b);
 			}
@@ -44,26 +82,25 @@ public UIActionSheet (string title, IUIActionSheetDelegate del, string cancelTit
 		/// <param name="title">A title to be displayed in the title area of the action sheet.</param>
 		/// <param name="del">A delegate that will respond to taps in the action sheet.</param>
 		/// <remarks>Pass <see langword="null" /> to <paramref name="title" /> if there is no text to display in the title area.</remarks>
-		public UIActionSheet (string title, IUIActionSheetDelegate del)
-		: this (title, del, null, null, (string) null) { }
+		public UIActionSheet (string? title, IUIActionSheetDelegate? del)
+		: this (title, del, null, null, (string?) null) { }
 
+		/// <summary>Initialize a <see cref="UIActionSheet" /> with a title.</summary>
 		/// <param name="title">A title to be displayed in the title area of the action sheet.</param>
-		///         <summary>Initialize an <see cref="UIKit.UIActionSheet" /> with a title.</summary>
-		///         <remarks>Pass <see langword="null" /> to <paramref name="title" /> if there is no text to display in the title area.</remarks>
-		public UIActionSheet (string title)
-		: this (title, null, null, null, (string) null) { }
+		/// <remarks>Pass <see langword="null" /> to <paramref name="title" /> if there is no text to display in the title area.</remarks>
+		public UIActionSheet (string? title)
+		: this (title, null, null, null, (string?) null) { }
 
+		/// <summary>Adds a button with the specified text.</summary>
 		/// <param name="name">Text for the button.</param>
-		///         <summary>Adds a button with the specified text.</summary>
-		///         <remarks>This method exists to allow the class to be initialized with C# 3.0 object initializers.   This is equivalent to calling AddButton (name).</remarks>
+		/// <remarks>This method exists to allow the class to be initialized with C# 3.0 object initializers. This is equivalent to calling <see cref="AddButton" />.</remarks>
 		public void Add (string name)
 		{
 			AddButton (name);
 		}
 
 		/// <summary>Obtains an enumerator that returns the button titles.</summary>
-		///         <returns>An IEnumerator.</returns>
-		///         <remarks>To be added.</remarks>
+		/// <returns>An <see cref="IEnumerator" />.</returns>
 		public IEnumerator GetEnumerator ()
 		{
 			for (int i = 0; i < ButtonCount; i++)

src/UIKit/UIActionSheet.cs

@@ -1726,7 +1726,6 @@ interface UIAccessibilityContentSizeCategoryImageAdjusting {
 		bool AdjustsImageSizeForAccessibilityContentSizeCategory { get; set; }
 	}
 
-	/// <include file="../docs/api/UIKit/UIActionSheet.xml" path="/Documentation/Docs[@DocId='T:UIKit.UIActionSheet']/*" />
 	[NoTV]
 	[BaseType (typeof (UIView), KeepRefUntil = "Dismissed", Delegates = new string [] { "WeakDelegate" }, Events = new Type [] { typeof (UIActionSheetDelegate) })]
 	[Deprecated (PlatformName.iOS, 8, 3, message: "Use 'UIAlertController' with 'UIAlertControllerStyle.ActionSheet' instead.")]