[bgen] Add default xml docs for properties that represents fields. (#22651)

Author: rolfbjarne

src/bgen/DocumentationManager.cs

@@ -22,15 +22,17 @@ public DocumentationManager (string assembly)
 		}
 	}
 
-	public void WriteDocumentation (StreamWriter sw, int indent, MemberInfo member, Func<XmlNode, XmlNode>? transformNode = null)
+	public bool WriteDocumentation (StreamWriter sw, int indent, MemberInfo member, Func<XmlNode, XmlNode>? transformNode = null)
 	{
 		if (!TryGetDocumentation (member, out var docs, transformNode))
-			return;
+			return false;
 
 		foreach (var line in docs) {
 			sw.Write ('\t', indent);
 			sw.WriteLine (line);
 		}
+
+		return true;
 	}
 
 	public bool TryGetDocumentation (MemberInfo member, [NotNullWhen (true)] out string []? documentation, Func<XmlNode, XmlNode>? transformNode = null)

src/bgen/Generator.cs

@@ -5421,9 +5421,9 @@ public void PrintExperimentalAttribute (ICustomAttributeProvider mi)
 		print ($"[Experimental (\"{e.DiagnosticId}\")]");
 	}
 
-	void WriteDocumentation (MemberInfo info, Func<XmlNode, XmlNode>? transformNode = null)
+	bool WriteDocumentation (MemberInfo info, Func<XmlNode, XmlNode>? transformNode = null)
 	{
-		DocumentationManager.WriteDocumentation (sw, indent, info, transformNode);
+		return DocumentationManager.WriteDocumentation (sw, indent, info, transformNode);
 	}
 
 	public bool TryComputeLibraryName (string attributeLibraryName, Type type, out string library_name, out string library_path)
@@ -6154,7 +6154,9 @@ public void Generate (Type type)
 						print ("static {0}? _{1};", fieldTypeName, field_pi.Name);
 					}
 
-					WriteDocumentation (field_pi);
+					if (!WriteDocumentation (field_pi) && BindingTouch.SupportsXmlDocumentation) {
+						print ($"/// <summary>Represents the value associated with the constant '{fieldAttr.SymbolName}'.</summary>");
+					}
 					PrintAttributes (field_pi, preserve: true, advice: true);
 					PrintObsoleteAttributes (field_pi);
 					print ("[Field (\"{0}\",  \"{1}\")]", fieldAttr.SymbolName, library_path ?? library_name);

tests/cecil-tests/Documentation.KnownFailures.txt

@@ -795,6 +795,12 @@
             Summary for TG1.TGProperty
             </summary>
         </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField">
+            <summary>TOuter.TInner.Field</summary>
+        </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField2">
+            <summary>Represents the value associated with the constant 'TOuterInnerField2'.</summary>
+        </member>
         <member name="T:XmlDocumentation.OptionsA">
             <summary>Summary for OptionsA.</summary>
         </member>

tests/generator/ExpectedXmlDocs.MacCatalyst.xml

@@ -795,6 +795,12 @@
             Summary for TG1.TGProperty
             </summary>
         </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField">
+            <summary>TOuter.TInner.Field</summary>
+        </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField2">
+            <summary>Represents the value associated with the constant 'TOuterInnerField2'.</summary>
+        </member>
         <member name="T:XmlDocumentation.TypeWithApparance">
             <summary>
             Summary for TypeWithApparance

tests/generator/ExpectedXmlDocs.iOS.xml

@@ -795,6 +795,12 @@
             Summary for TG1.TGProperty
             </summary>
         </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField">
+            <summary>TOuter.TInner.Field</summary>
+        </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField2">
+            <summary>Represents the value associated with the constant 'TOuterInnerField2'.</summary>
+        </member>
         <member name="T:XmlDocumentation.OptionsA">
             <summary>Summary for OptionsA.</summary>
         </member>

tests/generator/ExpectedXmlDocs.macOS.xml

@@ -795,6 +795,12 @@
             Summary for TG1.TGProperty
             </summary>
         </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField">
+            <summary>TOuter.TInner.Field</summary>
+        </member>
+        <member name="P:XmlDocumentation.TOuter.TInner.TOuterInnerField2">
+            <summary>Represents the value associated with the constant 'TOuterInnerField2'.</summary>
+        </member>
         <member name="T:XmlDocumentation.OptionsA">
             <summary>Summary for OptionsA.</summary>
         </member>

tests/generator/ExpectedXmlDocs.tvOS.xml

@@ -287,4 +287,16 @@ interface TClassDelegate {
 	}
 
 	interface ITClassDelegate { }
+
+	class TOuter {
+		[Static]
+		interface TInner {
+			/// <summary>TOuter.TInner.Field</summary>
+			[Field ("TOuterInnerField", "__Internal")]
+			NSString TOuterInnerField { get; }
+			// no xml comment, should get a default value
+			[Field ("TOuterInnerField2", "__Internal")]
+			NSString TOuterInnerField2 { get; }
+		}
+	}
 }