From c38787c74923cf93d2883a8be3d3f139442f249d Mon Sep 17 00:00:00 2001
From: Rolf Bjarne Kvinge <rolf@xamarin.com>
Date: Thu, 19 Feb 2026 12:41:24 +0100
Subject: [PATCH] [ObjCRuntime] Enable nullability and clean up
 CategoryAttribute.

This is file 6 of 7 files with nullability disabled in ObjCRuntime.

* Enable nullability (#nullable enable).
* Add nullability-aware API updates for category name metadata.
* Inline XML documentation from CategoryAttribute.xml into source and remove the include file.
* Improve XML documentation formatting, grammar, and cref usage.

Contributes towards https://github.com/dotnet/macios/issues/17285.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/api/ObjCRuntime/CategoryAttribute.xml | 68 -------------------
 src/ObjCRuntime/CategoryAttribute.cs       | 77 ++++++++++++++++------
 2 files changed, 57 insertions(+), 88 deletions(-)
 delete mode 100644 docs/api/ObjCRuntime/CategoryAttribute.xml

diff --git a/docs/api/ObjCRuntime/CategoryAttribute.xml b/docs/api/ObjCRuntime/CategoryAttribute.xml
deleted file mode 100644
index 80e9ecc63714..000000000000
--- a/docs/api/ObjCRuntime/CategoryAttribute.xml
+++ /dev/null
@@ -1,68 +0,0 @@
-<Documentation>
-  <Docs DocId="T:ObjCRuntime.CategoryAttribute">
-    <summary>Attribute used to flag a class as a category that extends the API of another type.</summary>
-    <remarks>
-      <para>
-	This attribute is applied to static user code classes and will
-	surface all of the exported methods and properties (those that
-	have the <see cref="Foundation.ExportAttribute" />)
-	to the provided system type.
-      </para>
-      <para>
-      </para>
-      <para>
-	This allows new methods to be introduced or implemented for
-	all types in the class.  For example, this can be used to
-	provide a global implementation of some method across all of
-	your types surfaced to Objective-C.
-      </para>
-      <para>
-	All managed extension methods must be static, but it's
-	possible to create Objective-C instance methods using the
-	standard syntax for extension methods in C#:
-      </para>
-      <example>
-        <code lang="csharp lang-csharp"><![CDATA[
-// Make "shouldAutoRotate" return true for all UIViewControllers in the application
-
-[Category (typeof (UIViewController))]
-static class MyViewControllerMethods {
-    [Export ("shouldAutorotate")]
-    static bool ShouldAutoRotate (this UIViewController self)
-    { 
-        return true; 
-    }
-
-    [Export ("supportedInterfaceOrientations")]
-    static UIInterfaceOrientationMask SupportedRotations (this UIViewController self) 
-    {
-        return UIInterfaceOrientationMask.All;
-    }
-}
-	]]></code>
-      </example>
-      <example>
-        <code lang="csharp lang-csharp"><![CDATA[
-// This example will add a native toUpper instance method to the NSString class, 
-// which can be invoked from Objective-C.
-
-[Category (typeof (NSString))]
-public static class MyStringCategory  
-{
-    [Export ("toUpper")]
-    static string ToUpper (this NSString self)
-    {
-        return self.ToString ().ToUpper ();
-    }
-}
-	]]></code>
-      </example>
-      <para>
-        If the managed class is not referenced by other managed code (and only called from Objective-C),
-        the managed linker will remove it. This can be avoided either by adding a
-        <see cref="Foundation.PreserveAttribute" /> attribute to the class, or by creating a custom linker definition file.
-      </para>
-    </remarks>
-    <related type="article" href="https://docs.microsoft.com/xamarin/cross-platform/deploy-test/linker">Custom Linker Configuration</related>
-  </Docs>
-</Documentation>
\ No newline at end of file
diff --git a/src/ObjCRuntime/CategoryAttribute.cs b/src/ObjCRuntime/CategoryAttribute.cs
index fa2b3e9a2b80..ec9137f1f948 100644
--- a/src/ObjCRuntime/CategoryAttribute.cs
+++ b/src/ObjCRuntime/CategoryAttribute.cs
@@ -1,39 +1,76 @@
 //
-// CategoryAttribyute.cs:
+// CategoryAttribute.cs:
 //
 // Authors:
 //   Rolf Bjarne Kvinge <rolf@xamarin.com>
 //
 // Copyright 2015 Xamarin Inc.
 
-// Disable until we get around to enable + fix any issues.
-#nullable disable
+#nullable enable
 
 namespace ObjCRuntime {
-	/// <include file="../../docs/api/ObjCRuntime/CategoryAttribute.xml" path="/Documentation/Docs[@DocId='T:ObjCRuntime.CategoryAttribute']/*" />
+	/// <summary>Attribute used to flag a class as a category that extends another type.</summary>
+	/// <remarks>
+	///   <para>This attribute is applied to static user-code classes and surfaces all exported methods and properties (those with the <see cref="Foundation.ExportAttribute"/>) to the provided system type.</para>
+	///   <para>This allows new methods to be introduced or implemented for all types in the class. For example, this can be used to provide a global implementation of some method across all your types surfaced to Objective-C.</para>
+	///   <para>All managed extension methods must be static, but it is possible to create Objective-C instance methods using the standard syntax for extension methods in C#:</para>
+	///   <example>
+	///     <code lang="csharp"><![CDATA[
+	/// // Make "shouldAutoRotate" return true for all UIViewControllers in the application
+	///
+	/// [Category (typeof (UIViewController))]
+	/// static class MyViewControllerMethods {
+	///     [Export ("shouldAutorotate")]
+	///     static bool ShouldAutoRotate (this UIViewController self)
+	///     {
+	///         return true;
+	///     }
+	///
+	///     [Export ("supportedInterfaceOrientations")]
+	///     static UIInterfaceOrientationMask SupportedRotations (this UIViewController self)
+	///     {
+	///         return UIInterfaceOrientationMask.All;
+	///     }
+	/// }
+	/// ]]></code>
+	///   </example>
+	///   <example>
+	///     <code lang="csharp"><![CDATA[
+	/// // This example adds a native toUpper instance method to the NSString class,
+	/// // which can be invoked from Objective-C.
+	///
+	/// [Category (typeof (NSString))]
+	/// public static class MyStringCategory
+	/// {
+	///     [Export ("toUpper")]
+	///     static string ToUpper (this NSString self)
+	///     {
+	///         return self.ToString ().ToUpper ();
+	///     }
+	/// }
+	/// ]]></code>
+	///   </example>
+	///   <para>If the managed class is not referenced by other managed code (and is only called from Objective-C), the managed linker may remove it. This can be avoided by either adding a <see cref="Foundation.PreserveAttribute"/> attribute to the class, or by creating a custom linker definition file.</para>
+	///   <para>See <see href="https://docs.microsoft.com/xamarin/cross-platform/deploy-test/linker">Custom Linker Configuration</see> for more information.</para>
+	/// </remarks>
 	[AttributeUsage (AttributeTargets.Class)]
 	public class CategoryAttribute : Attribute {
-		/// <param name="type">The Objective-C type to extend.   This must be a subclass of NSObject (or NSObject itself).</param>
-		///         <summary>The type that this category extends.</summary>
-		///         <remarks>
-		///         </remarks>
+		/// <summary>Initializes a new instance of the <see cref="CategoryAttribute"/> class.</summary>
+		/// <param name="type">The Objective-C type to extend. This must be a subclass of <see cref="Foundation.NSObject"/> (or <see cref="Foundation.NSObject"/> itself).</param>
 		public CategoryAttribute (Type type)
 		{
 			Type = type;
 		}
 
-		/// <summary>The type that this category extends.</summary>
-		///         <value>
-		///         </value>
-		///         <remarks>
-		///         </remarks>
+		/// <summary>Gets or sets the type that this category extends.</summary>
+		/// <value>The type this category extends.</value>
 		public Type Type { get; set; }
-		/// <summary>The name of the category.</summary>
-		///         <value>
-		///         </value>
-		///         <remarks>
-		///           <para>This must be a valid Objective-C type name, but is otherwise unused.</para>
-		///         </remarks>
-		public string Name { get; set; }
+
+		/// <summary>Gets or sets the name of the category.</summary>
+		/// <value>The category name, or <see langword="null"/> to use the managed type name.</value>
+		/// <remarks>
+		/// <para>This must be a valid Objective-C type name, but is otherwise unused.</para>
+		/// </remarks>
+		public string? Name { get; set; }
 	}
 }