[Foundation] Fix nullability in NSMutableDictionary. (#24428)

* Enable nullability for NSMutableDictionary.cs.
* Fix interface implementations to match nullability contracts (IDictionary, IDictionary<NSObject, NSObject>).
* Make indexers' return type allow null, but disallow setting null values.
* Remove all 'To be added.' XML comments.
* Add comprehensive XML documentation for all public methods, properties, and indexers.
* Use proper 'see cref' attributes for type references in documentation.
* Fix ArgumentNullException to use nameof for parameter names.
* Remove an unused constructor.

Also add NSMutableDictionary tests for missing key behavior:

* Add tests to verify that accessing missing keys returns null.
* Test all indexer overloads (string, NSObject, NSString).
* Test ObjectForKey method with missing keys.
* Test TryGetValue with missing keys returns false and null output.
* Test IDictionary interface implementations (indexer and Contains).
* Ensure existing keys still work correctly after testing missing keys.

These tests document and verify the expected behavior when fetching
values for keys that don't exist in the dictionary.

This is file 34 of 47 files with nullability disabled in Foundation.

Contributes towards #17285.

---------

Co-authored-by: GitHub Copilot <copilot@github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

src/AudioToolbox/AudioFile.cs

@@ -2376,10 +2376,11 @@ public unsafe byte []? ID3Tag {
 		public AudioFileInfoDictionary? InfoDictionary {
 			get {
 				var ptr = GetIntPtr (AudioFileProperty.InfoDictionary);
-				if (ptr == IntPtr.Zero)
+				var dict = Runtime.GetNSObject<NSMutableDictionary> (ptr, owns: true);
+				if (dict is null)
 					return null;
 
-				return new AudioFileInfoDictionary (new NSMutableDictionary (ptr, true));
+				return new AudioFileInfoDictionary (dict);
 			}
 		}
 

src/AudioToolbox/AudioToolbox.cs

@@ -39,8 +39,8 @@ internal InstrumentInfo (NSDictionary d)
 		/// <summary>To be added.</summary>
 		///         <value>To be added.</value>
 		///         <remarks>To be added.</remarks>
-		public string Name {
-			get { return Dictionary [NameKey].ToString (); }
+		public string? Name {
+			get { return Dictionary [NameKey]?.ToString (); }
 		}
 
 		/// <summary>To be added.</summary>

src/CoreText/CTFont.cs

@@ -429,7 +429,10 @@ public string? Name {
 		///         <remarks>To be added.</remarks>
 		public FontFeatureGroup FeatureGroup {
 			get {
-				return (FontFeatureGroup) (int) (NSNumber) Dictionary [CTFontFeatureKey.Identifier];
+				var number = (NSNumber?) Dictionary [CTFontFeatureKey.Identifier];
+				if (number is null)
+					return default;
+				return (FontFeatureGroup) (int) number;
 			}
 		}
 
@@ -591,7 +594,10 @@ internal static CTFontFeatureSelectors Create (FontFeatureGroup featureGroup, NS
 		///         <remarks>To be added.</remarks>
 		protected int FeatureWeak {
 			get {
-				return (int) (NSNumber) Dictionary [CTFontFeatureSelectorKey.Identifier];
+				var number = (NSNumber?) Dictionary [CTFontFeatureSelectorKey.Identifier];
+				if (number is null)
+					return default;
+				return (int) number;
 			}
 		}
 
@@ -2327,7 +2333,10 @@ internal CTFontFeatureSettings (NSDictionary dictionary)
 		///         <remarks>To be added.</remarks>
 		public FontFeatureGroup FeatureGroup {
 			get {
-				return (FontFeatureGroup) (int) (NSNumber) Dictionary [CTFontFeatureKey.Identifier];
+				var number = (NSNumber?) Dictionary [CTFontFeatureKey.Identifier];
+				if (number is null)
+					return default;
+				return (FontFeatureGroup) (int) number;
 			}
 		}
 
@@ -2336,7 +2345,10 @@ public FontFeatureGroup FeatureGroup {
 		///         <remarks>To be added.</remarks>
 		public int FeatureWeak {
 			get {
-				return (int) (NSNumber) Dictionary [CTFontFeatureSelectorKey.Identifier];
+				var number = (NSNumber?) Dictionary [CTFontFeatureSelectorKey.Identifier];
+				if (number is null)
+					return default;
+				return (int) number;
 			}
 		}
 	}
@@ -2375,32 +2387,32 @@ public CTFontVariationAxes (NSDictionary dictionary)
 		/// <summary>To be added.</summary>
 		///         <value>To be added.</value>
 		///         <remarks>To be added.</remarks>
-		public NSNumber Identifier {
-			get { return (NSNumber) Dictionary [CTFontVariationAxisKey.Identifier]; }
+		public NSNumber? Identifier {
+			get { return (NSNumber?) Dictionary [CTFontVariationAxisKey.Identifier]; }
 			set { Adapter.SetValue (Dictionary, CTFontVariationAxisKey.Identifier, value); }
 		}
 
 		/// <summary>To be added.</summary>
 		///         <value>To be added.</value>
 		///         <remarks>To be added.</remarks>
-		public NSNumber MinimumValue {
-			get { return (NSNumber) Dictionary [CTFontVariationAxisKey.MinimumValue]; }
+		public NSNumber? MinimumValue {
+			get { return (NSNumber?) Dictionary [CTFontVariationAxisKey.MinimumValue]; }
 			set { Adapter.SetValue (Dictionary, CTFontVariationAxisKey.MinimumValue, value); }
 		}
 
 		/// <summary>To be added.</summary>
 		///         <value>To be added.</value>
 		///         <remarks>To be added.</remarks>
-		public NSNumber MaximumValue {
-			get { return (NSNumber) Dictionary [CTFontVariationAxisKey.MaximumValue]; }
+		public NSNumber? MaximumValue {
+			get { return (NSNumber?) Dictionary [CTFontVariationAxisKey.MaximumValue]; }
 			set { Adapter.SetValue (Dictionary, CTFontVariationAxisKey.MaximumValue, value); }
 		}
 
 		/// <summary>To be added.</summary>
 		///         <value>To be added.</value>
 		///         <remarks>To be added.</remarks>
-		public NSNumber DefaultValue {
-			get { return (NSNumber) Dictionary [CTFontVariationAxisKey.DefaultValue]; }
+		public NSNumber? DefaultValue {
+			get { return (NSNumber?) Dictionary [CTFontVariationAxisKey.DefaultValue]; }
 			set { Adapter.SetValue (Dictionary, CTFontVariationAxisKey.DefaultValue, value); }
 		}
 

src/CoreText/CTFontDescriptor.cs

@@ -315,7 +315,7 @@ public IEnumerable<CTFontDescriptor>? CascadeList {
 		///         <remarks>
 		///         </remarks>
 		public NSCharacterSet? CharacterSet {
-			get { return (NSCharacterSet) Dictionary [CTFontDescriptorAttributeKey.CharacterSet]; }
+			get { return (NSCharacterSet) Dictionary [CTFontDescriptorAttributeKey.CharacterSet]!; }
 			set { Adapter.SetValue (Dictionary, CTFontDescriptorAttributeKey.CharacterSet!, value); }
 		}
 
@@ -515,7 +515,7 @@ public bool? WeakEnabled {
 		///         </remarks>
 		public bool Enabled {
 			get {
-				var value = (NSNumber) Dictionary [CTFontDescriptorAttributeKey.Enabled];
+				var value = (NSNumber?) Dictionary [CTFontDescriptorAttributeKey.Enabled];
 				if (value is null)
 					return false;
 				return value.Int32Value != 0;

src/CoreText/CTTextTab.cs

@@ -63,8 +63,8 @@ public CTTextTabOptions (NSDictionary dictionary)
 		/// <summary>To be added.</summary>
 		///         <value>To be added.</value>
 		///         <remarks>To be added.</remarks>
-		public NSCharacterSet ColumnTerminators {
-			get { return (NSCharacterSet) Dictionary [CTTextTabOptionKey.ColumnTerminators]; }
+		public NSCharacterSet? ColumnTerminators {
+			get { return (NSCharacterSet?) Dictionary [CTTextTabOptionKey.ColumnTerminators]!; }
 			set { Adapter.SetValue (Dictionary, CTTextTabOptionKey.ColumnTerminators, value); }
 		}
 	}

src/Foundation/NSDictionary.cs

@@ -23,6 +23,7 @@
 //
 using System.Collections;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 
 // Disable until we get around to enable + fix any issues.
 #nullable disable
@@ -472,13 +473,13 @@ public bool TryGetValue (NSObject key, out NSObject value)
 			return value is not null;
 		}
 
-		/// <param name="key">Key to lookup</param>
-		/// <summary>Returns the value associated from a key in the dictionary, or null if the key is not found.</summary>
-		/// <value>
-		///         </value>
-		/// <remarks>
-		///         </remarks>
-		public virtual NSObject this [NSObject key] {
+#nullable enable
+		/// <summary>Gets the object associated with the specified key.</summary>
+		/// <param name="key">The key of the object to get.</param>
+		/// <value>The object associated with the specified key.</value>
+		/// <remarks>Returns <see langword="null" /> if the key wasn't found.</remarks>
+		[DisallowNull] // don't allow setting null values
+		public virtual NSObject? this [NSObject key] {
 			get {
 				return ObjectForKey (key);
 			}
@@ -487,13 +488,12 @@ public virtual NSObject this [NSObject key] {
 			}
 		}
 
-		/// <param name="key">Key to lookup</param>
-		/// <summary>Returns the value associated from a key in the dictionary, or null if the key is not found.</summary>
-		/// <value>
-		///         </value>
-		/// <remarks>
-		///         </remarks>
-		public virtual NSObject this [NSString key] {
+		/// <summary>Gets the object associated with the specified key.</summary>
+		/// <param name="key">The key of the object to get.</param>
+		/// <value>The object associated with the specified key.</value>
+		/// <remarks>Returns <see langword="null" /> if the key wasn't found.</remarks>
+		[DisallowNull] // don't allow setting null values
+		public virtual NSObject? this [NSString key] {
 			get {
 				return ObjectForKey (key);
 			}
@@ -502,12 +502,13 @@ public virtual NSObject this [NSString key] {
 			}
 		}
 
-		/// <param name="key">Key to lookup</param>
-		/// <summary>Returns the value associated from a key in the dictionary, or null if the key is not found.</summary>
-		/// <value>
-		///         </value>
-		/// <remarks>The string will be marshalled as an NSString before performing the lookup.</remarks>
-		public virtual NSObject this [string key] {
+		/// <summary>Gets the object associated with the specified key.</summary>
+		/// <param name="key">The key of the object to get.</param>
+		/// <value>The object associated with the specified key.</value>
+		/// <exception cref="ArgumentNullException">Thrown when <paramref name="key"/> is <see langword="null"/>.</exception>
+		/// <remarks>Returns <see langword="null" /> if the key wasn't found.</remarks>
+		[DisallowNull] // don't allow setting null values
+		public virtual NSObject? this [string key] {
 			get {
 				if (key is null)
 					throw new ArgumentNullException ("key");
@@ -522,6 +523,7 @@ public virtual NSObject this [string key] {
 				throw new NotSupportedException ();
 			}
 		}
+#nullable disable
 
 		ICollection<NSObject> IDictionary<NSObject, NSObject>.Keys {
 			get { return Keys; }