From 5e06af726006c5d805799ed4752e520ecbb8a0e3 Mon Sep 17 00:00:00 2001
From: Rolf Bjarne Kvinge <rolf@xamarin.com>
Date: Wed, 12 Nov 2025 12:28:00 +0100
Subject: [PATCH] [src] Remove 'remarks' nodes from enum fields, and add a
 test.

We get suggestions in the doc publishing workflow about 'remarks' in enum
fields (they're ignored), so avoid this by not having 'remarks' in enum
fields.
---
 src/Foundation/NSObject2.cs        |  1 -
 src/avfoundation.cs                |  1 -
 tests/cecil-tests/Documentation.cs | 29 +++++++++++++++++++++++++++++
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/src/Foundation/NSObject2.cs b/src/Foundation/NSObject2.cs
index b93f509d7761..0e5cd8df76f0 100644
--- a/src/Foundation/NSObject2.cs
+++ b/src/Foundation/NSObject2.cs
@@ -53,7 +53,6 @@ namespace Foundation {
 	[SupportedOSPlatform ("tvos")]
 	public enum NSObjectFlag {
 		/// <summary>Sentinel instance.</summary>
-		///         <remarks>To be added.</remarks>
 		Empty,
 	}
 
diff --git a/src/avfoundation.cs b/src/avfoundation.cs
index ef11f0b4f6d4..9e3bbf9c47d9 100644
--- a/src/avfoundation.cs
+++ b/src/avfoundation.cs
@@ -433,7 +433,6 @@ enum AVFileTypes {
 		QuickTimeMovie = 0,
 
 		/// <summary>Indicates the MPEG-4 format.</summary>
-		/// <remarks>Typically files using format has an .mp4 extension.</remarks>
 		[Field ("AVFileTypeMPEG4")]
 		Mpeg4 = 1,
 
diff --git a/tests/cecil-tests/Documentation.cs b/tests/cecil-tests/Documentation.cs
index 88f8879ce45c..153576a45097 100644
--- a/tests/cecil-tests/Documentation.cs
+++ b/tests/cecil-tests/Documentation.cs
@@ -169,6 +169,35 @@ public void VerifyEveryVisibleMemberIsDocumented ()
 			}
 		}
 
+		[Test]
+		public void NoRemarksOnEnumFields ()
+		{
+			var xmlEnumFieldsWithRemarks = new Dictionary<string, string> ();
+			foreach (var info in Helper.NetPlatformAssemblyDefinitions) {
+				// create a dictionary lookup of all types in the assembly
+				var allTypes = info.Assembly.EnumerateTypes ().ToDictionary (k => k.FullName.Replace ('/', '.'), v => v);
+				// load the xml documentation, filtering to fields with a <remarks> section
+				var xmlPath = Path.ChangeExtension (info.Path, ".xml");
+				var doc = new XmlDocument ();
+				doc.LoadWithoutNetworkAccess (xmlPath);
+				foreach (XmlNode node in doc.SelectNodes ("/doc/members/member[starts-with(@name,'F:') and ./remarks]")!) {
+					var name = node.Attributes! ["name"]!.Value;
+
+					// extract the type name from the member name, and use it to check if the field's type is an enum
+					var typename = name [2..name.LastIndexOf ('.')];
+					var type = allTypes [typename];
+					if (!type.IsEnum)
+						continue;
+
+					// the field has a <remarks> section, and it's an enum field - record it as a failure
+					var remarks = node.SelectSingleNode ("remarks")?.InnerText ?? "";
+					xmlEnumFieldsWithRemarks [name] = remarks;
+				}
+			}
+
+			Assert.That (xmlEnumFieldsWithRemarks, Is.Empty, "No enum fields with <remarks> documentation.");
+		}
+
 		static HashSet<AssemblyApi> GetDocumentedMembers (string xml)
 		{
 			var rv = new HashSet<AssemblyApi> ();