From d6c1667e56583ab70219abfd7edba69b04d58dbe Mon Sep 17 00:00:00 2001
From: Peter Collins <pecolli@microsoft.com>
Date: Thu, 16 Jun 2022 15:09:09 -0400
Subject: [PATCH] [Javadoc] Merge return values on bound properties

Context: https://developer.android.com/reference/android/animation/Keyframe#setInterpolator(android.animation.TimeInterpolator)

The Java source for `Keyframe.setInterpolator` incidentally includes a
`@return` tag, even though the return type is void:

    /**
     * Sets the optional interpolator for this Keyframe. A value of <code>null</code> indicates
     * that there is no interpolation, which is the same as linear interpolation.
     *
     * @return The optional interpolator for this Keyframe.
     */
    public void setInterpolator(TimeInterpolator interpolator) {
        mInterpolator = interpolator;
    }

This causes us to generate multiple `<returns>` C# doc comment tags on
the `Android.Animation.Keyframe.Interpolator` property, as the setter
and getter both include the same `@return` tag:

    /// <summary>Gets the optional interpolator for this Keyframe. -or- Sets the optional interpolator for this Keyframe.</summary>
    /// ...
    /// <returns>The optional interpolator for this Keyframe.</returns>
    /// <returns>The optional interpolator for this Keyframe.</returns>
    public virtual unsafe Android.Animation.ITimeInterpolator? Interpolator {

The `mdoc.exe` tool does not handle this well, and will continously
append a `<value>` element on this property every time the tool runs
against our improperly formatted C# doc comments:

    <Docs>
      <summary>Gets the optional interpolator for this Keyframe. -or- Sets the optional interpolator for this Keyframe.</summary>
      <value>The optional interpolator for this Keyframe.</value>
      <value>The optional interpolator for this Keyframe.</value>
      <value>The optional interpolator for this Keyframe.</value>
      ...
      <since version="Added in API level 11" />
    </Docs>

Fix this by attempting to merge `returns` elements for property getters
and setters.
---
 tools/generator/SourceWriters/BoundProperty.cs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/tools/generator/SourceWriters/BoundProperty.cs b/tools/generator/SourceWriters/BoundProperty.cs
index 329a30a9d..df2c87c09 100644
--- a/tools/generator/SourceWriters/BoundProperty.cs
+++ b/tools/generator/SourceWriters/BoundProperty.cs
@@ -179,6 +179,7 @@ void AddJavadocs (Property property)
 
 				MergeSummary (memberDocs, setterDocs);
 				MergeRemarks (memberDocs, setterDocs);
+				MergeReturns (memberDocs, setterDocs);
 
 				memberDocs.Add (setterDocs.Nodes ());
 			}
@@ -223,5 +224,20 @@ static void MergeRemarks (XElement mergeInto, XElement mergeFrom)
 				toContent.Add (fromContent.Nodes ());
 			}
 		}
+
+		static void MergeReturns (XElement mergeInto, XElement mergeFrom)
+		{
+			var toContent = mergeInto.Element ("returns");
+			var fromContent = mergeFrom.Element ("returns");
+
+			if (toContent != null && fromContent != null) {
+				if (toContent.Value == fromContent.Value) {
+					fromContent.Remove ();
+				} else {
+					toContent.Add (" ");
+					toContent.Add (fromContent.Nodes ());
+				}
+			}
+		}
 	}
 }