[generator] Improve Javadoc remarks on properties (#911)

Fixes: #905

Commit 7574f16 added support for `generator --with-javadoc-xml=JDOC`
and `generator --doc-copyright=COPYRIGHT`, with the contents of
`COPYRIGHT` being appended to the `<remarks/>` section for member.

This "append to `<remarks/>`" logic happened *before* docs for
property getters and setters were merged.  Consequently, the
`COPYRIGHT` contents could be "duplicated":

	<summary>Return the current requested orientation of the activity. -or- Change the desired orientation of this activity.</summary>
	<value>Returns an orientation constant as used in
	    <c>ActivityInfo#screenOrientation ActivityInfo.screenOrientation</c>.</value>
	<remarks>
	  <para>Property getter documentation:</para>
	  <para>
	    <format type="text/html">
	      <a href="https://developer.android.com/reference/android/app/Activity#getRequestedOrientation()" title="Reference documentation">Java documentation for <code>android.app.Activity.getRequestedOrientation()</code>.</a>
	    </format>
	  </para>
	  <para>Portions of this page are modifications based on…</para>
	  <para>Property setter documentation:</para>
	  <para>
	    <format type="text/html">
	      <a href="https://developer.android.com/reference/android/app/Activity#setRequestedOrientation(int)" title="Reference documentation">Java documentation for <code>android.app.Activity.setRequestedOrientation(int)</code>.</a>
	    </format>
	  </para>
	  <para>Portions of this page are modifications based on…</para>
	</remarks>

Rework things so that property getters and setters no longer
automatically include `COPYRIGHT` into their `<remarks/>` content.
Instead, append `COPYRIGHT` to the `<remarks/>` element *after* the
get- and set- docs have been merged.

The custom `<summary>` and `<remarks>` merging that happens for
properties will now also use `XContainer.Nodes()` instead of
`XContainer.DescendantNodes()` to avoid content duplication.

The result removes the "Portions of this page…" duplication:

	<summary>Return the current requested orientation of the activity. -or- Change the desired orientation of this activity.</summary>
	<value>Returns an orientation constant as used in
	    <c>ActivityInfo#screenOrientation ActivityInfo.screenOrientation</c>.</value>
	<remarks>
	  <para>Property getter documentation:</para>
	  <para>
	    <format type="text/html">
	      <a href="https://developer.android.com/reference/android/app/Activity#getRequestedOrientation()" title="Reference documentation">Java documentation for <code>android.app.Activity.getRequestedOrientation()</code>.</a>
	    </format>
	  </para>
	  <para>Property setter documentation:</para>
	  <para>
	    <format type="text/html">
	      <a href="https://developer.android.com/reference/android/app/Activity#setRequestedOrientation(int)" title="Reference documentation">Java documentation for <code>android.app.Activity.setRequestedOrientation(int)</code>.</a>
	    </format>
	  </para>
	  <para>Portions of this page are modifications based on…</para>
	</remarks>

Author: pjcollins

tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs

@@ -22,11 +22,13 @@ public sealed class JavadocInfo {
 
 		public  XElement[]      ExtraRemarks        { get; set; }
 
+		public  XElement[]      Copyright           { get; set; }
+
 		public  XmldocStyle     XmldocStyle         { get; set; }
 
 		string  MemberDescription;
 
-		public static JavadocInfo CreateInfo (XElement element, XmldocStyle style)
+		public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool appendCopyrightExtra = true)
 		{
 			if (element == null) {
 				return null;
@@ -39,13 +41,16 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style)
 			string declaringMemberName      = desc.DeclaringMemberName;
 			var declaringMemberJniSignature = desc.DeclaringMemberJniSignature;
 
-			XElement[]  extra               = GetExtra (element, style, declaringJniType, declaringMemberName, declaringMemberJniSignature);
+			var extras                      = GetExtra (element, style, declaringJniType, declaringMemberName, declaringMemberJniSignature, appendCopyrightExtra);
+			XElement[] extra                = extras.Extras;
+			XElement[] copyright            = extras.Copyright;
 
 			if (string.IsNullOrEmpty (javadoc) && extra == null)
 				return null;
 
 			var info = new JavadocInfo () {
 				ExtraRemarks        = extra,
+				Copyright           = copyright,
 				Javadoc             = javadoc,
 				MemberDescription   = declaringMemberName == null
 					? declaringJniType
@@ -78,10 +83,10 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style)
 			return (declaringJniType, declaringMemberName, declaringMemberJniSignature);
 		}
 
-		static XElement[] GetExtra (XElement element, XmldocStyle style, string declaringJniType, string declaringMemberName, string declaringMemberJniSignature)
+		static (XElement[] Extras, XElement[] Copyright) GetExtra (XElement element, XmldocStyle style, string declaringJniType, string declaringMemberName, string declaringMemberJniSignature, bool appendCopyrightExtra)
 		{
 			if (!style.HasFlag (XmldocStyle.IntelliSenseAndExtraRemarks))
-				return null;
+				return (null, null);
 
 			XElement javadocMetadata    = null;
 			while (element != null) {
@@ -93,6 +98,7 @@ static XElement[] GetExtra (XElement element, XmldocStyle style, string declarin
 			}
 
 			List<XElement>  extra   = null;
+			IEnumerable<XElement>  copyright = null;
 			if (javadocMetadata != null) {
 				var link            = javadocMetadata.Element ("link");
 				var urlPrefix       = (string) link.Attribute ("prefix");
@@ -105,9 +111,12 @@ static XElement[] GetExtra (XElement element, XmldocStyle style, string declarin
 				}
 				extra           = new List<XElement> ();
 				extra.Add (docLink);
-				extra.AddRange (javadocMetadata.Element ("copyright").Elements ());
+				copyright = javadocMetadata.Element ("copyright").Elements ();
+				if (appendCopyrightExtra) {
+					extra.AddRange (copyright);
+				}
 			}
-			return extra?.ToArray ();
+			return (extra?.ToArray (), copyright?.ToArray ());
 		}
 
 		static ApiLinkStyle ParseApiLinkStyle (string style)

tools/generator/Java.Interop.Tools.Generator.Transformation/JavadocFixups.cs

@@ -70,11 +70,11 @@ static void AddJavadoc (GenBase type, Dictionary<string, XElement> typeJavadocs,
 			foreach (var property in type.Properties) {
 				if (property.Getter != null && property.Getter.JavadocInfo == null) {
 					var getterJavadoc           = GetMemberJavadoc (typeJavadoc, "method", property.Getter.JavaName, property.Getter.JniSignature);
-					property.Getter.JavadocInfo = JavadocInfo.CreateInfo (getterJavadoc?.Parent, style);
+					property.Getter.JavadocInfo = JavadocInfo.CreateInfo (getterJavadoc?.Parent, style, appendCopyrightExtra: false);
 				}
 				if (property.Setter != null && property.Setter.JavadocInfo == null) {
 					var setterJavadoc           = GetMemberJavadoc (typeJavadoc, "method", property.Setter.JavaName, property.Setter.JniSignature);
-					property.Setter.JavadocInfo = JavadocInfo.CreateInfo (setterJavadoc?.Parent, style);
+					property.Setter.JavadocInfo = JavadocInfo.CreateInfo (setterJavadoc?.Parent, style, appendCopyrightExtra: false);
 				}
 			}
 

tools/generator/SourceWriters/BoundProperty.cs

@@ -158,18 +158,28 @@ void AddJavadocs (Property property)
 				return;
 
 			var memberDocs = new XElement ("member");
+			XElement[] copyrightExtra = null;
 
 			if (property.Getter?.JavadocInfo != null) {
 				memberDocs.Add (property.Getter.JavadocInfo.ParseJavadoc ());
+				copyrightExtra = property.Getter.JavadocInfo.Copyright;
 			}
 
 			if (property.Setter?.JavadocInfo != null) {
 				var setterDocs  = new XElement ("member", property.Setter.JavadocInfo.ParseJavadoc ());
+				if (copyrightExtra == null) {
+					copyrightExtra = property.Setter.JavadocInfo.Copyright;
+				}
 
 				MergeSummary (memberDocs, setterDocs);
 				MergeRemarks (memberDocs, setterDocs);
 
-				memberDocs.Add (setterDocs.DescendantNodes ());
+				memberDocs.Add (setterDocs.Nodes ());
+			}
+
+			if (copyrightExtra != null) {
+				var remarks = memberDocs.Element ("remarks");
+				remarks?.Add (copyrightExtra);
 			}
 
 			JavadocInfo.AddComments (Comments, memberDocs.Elements ());
@@ -187,7 +197,7 @@ static void MergeSummary (XElement mergeInto, XElement mergeFrom)
 			else if (toContent != null && fromContent != null) {
 				fromContent.Remove ();
 				toContent.Add (" -or- ");
-				toContent.Add (fromContent.DescendantNodes ());
+				toContent.Add (fromContent.Nodes ());
 			}
 		}
 
@@ -204,7 +214,7 @@ static void MergeRemarks (XElement mergeInto, XElement mergeFrom)
 				fromContent.Remove ();
 				toContent.AddFirst (new XElement ("para", "Property getter documentation:"));
 				toContent.Add (new XElement ("para", "Property setter documentation:"));
-				toContent.Add (fromContent.DescendantNodes ());
+				toContent.Add (fromContent.Nodes ());
 			}
 		}
 	}