[generator] Handle multiple @return javadoc values

[pjcollins]

Context: dotnet/android#5485

In an attempt to generate updated documentation for API 30 I've noticed
a minor issue in generator. When a <javadoc> element contains
multiple @return values, we will generate multiple <returns> elements
in our C# documentation. This results in invalid C# documentation with
partially missing return information, and the second <returns> element
value is not displayed in IDE intellisense. This also causes an issue
when the xml is processed by mdoc. These extra return lines will
continue to be appended to the mdoc output every time the tool is ran
against the invalid Mono.Android.xml.

[jonpryor]

This can't be null; .First() requires that an element be returned, and unless we have a bug and we do .Returns.Add(null), there should only be non-null elements within jdi.Returns.

If we want to allow null, use .FirstOrDefault().

Actually, on review this entire block doesn't quite make sense to me: r itself shouldn't change from r.Add(), and thus this should be a no-op (unless jdi.Returns somehow has > 1 element in it? But how could that happen?)

FinishParse (context, parseNode).Returns.Clear ();
FinishParse (context, parseNode).Returns.Add (r);

Neither of the above statements should be needed.

[pjcollins]

The null check was intended to handle the possibility of jdi.Returns.First () not being an XElement, though I think we only ever add XElements to this ICollection<XNode> in the section above and so the check probably shouldn't be needed.

The FinishParse (context, parseNode).Returns collection will have more than zero elements in it when the <javadoc> entry that is being parsed has multiple @return values in it, as shown in the test addition below. The Returns.Clear and Returns.Add additions do look to be redundant here though, I will clean that up.

[jonpryor]

I'm half surprised that @tag parsing isn't requiring newlines in there, and that we don't need \n@return ……

[jonpryor]

Another test case I'm concerned about properties: https://github.com/xamarin/java.interop/blob/12e670a8560f69581d3a3adf0a9d91e8ce8c9afa/tools/generator/SourceWriters/BoundProperty.cs#L194-L209

Properties may contain the docs for two separate methods, the get and set methods, and if "somehow" there are > 2 @remarks blocks between the two methods, I don't think they're be "fully" merged, as there could be multiple <remarks/> elements under both mergeInto and mergeFrom!

…though perhaps now after the fix within this PR, which should limit things to only one <remarks/> per method…

[jonpryor]

For review:

Context: https://github.com/xamarin/xamarin-android/pull/5485

In an attempt to generate updated documentation for API-30 I noticed
a minor issue in generator Javadoc import (7574f166): when a
`<javadoc/>` element contains multiple `@return` values:

	<class name="Example" …>
	  <method name="m" …>
	    <javadoc>
	      <![CDATA[
	        …
	        @return some docs
	        @return additional docs
	      ]]>
	    </javadoc>
	  </method>
	</class>


We would generate multiple `<returns/>` elements, one for each
`@return`:

	partial class Example {
	    /// <returns>some docs</returns>
	    /// <returns>additional docs</returns>
	    public void M() {…}
	}

This is "fine", as far as the C# compiler is concerned, which results
in a Documentation XML file containing both `<returns/>`:

	<doc>
	  <members>
	    <member name="M:Example.M()">
	      <returns>some docs</returns>
	      <returns>additional docs</returns>
	    </member>
	  </members>
	</doc>

The problem is when we later try to *import* this documentation via
`mdoc update --import`, as xamarin/xamarin-android#5485 does;
if mdoc 5.7.4.9 is used (included with macOS Mono 6.12):

	$ mdoc update -o docs assembly.dll --import assembly.xml

The resulting imported [**mdoc**(5)][0] documentation only contains
the *first* element:

	<Docs>
	  <summary>To be added.</summary>
	  <returns>some docs</returns>
	  <remarks>To be added.</remarks>
	</Docs>

Using [mdoc 5.8.0][1] will preserve both `<returns/>` elements, but
that doesn't mean that "higher level" tooling such as HTML rendering
or IntelliSense will properly support this construct.

Update the Javadoc importer so that multiple `@returns` blocks are
*merged* into a single `<returns/>` element:

	partial class Example {
	    /// <returns>some docs additional docs</returns>
	    public void M() {…}
	}

[0]: http://docs.go-mono.com/?link=man%3amdoc(5)
[1]: https://www.nuget.org/packages/mdoc/5.8.0