[generator] Add --doc-comment-verbosity=intellisense+extraremarks

Context: dotnet/android@a7413a2
Context: https://github.com/xamarin/android-api-docs
Context: https://github.com/xamarin/android-api-docs/blob/035344f961fd391bcad9715ea690afa3b88d6142/docs/Mono.Android/en/Java.Lang/Object.xml#L34-L41

dotnet/android@a7413a23 asked:

> What do we want?  Updated documentation!

About that…

Our existing documentation at [xamarin/android-api-docs][0] includes
a copyright notice for every member, e.g.

	<remarks>
	  <para>
	    <format type="text/html">
	      <a href="https://developer.android.com/reference/java/lang/Object" title="Reference documentation">Android platform documentation</a>
	    </format>
	  </para>
	  <para>Portions of this page are modifications based on work created and shared by the <format type="text/html"><a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a></format> and used according to terms described in the <format type="text/html"><a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format></para>
	</remarks>

The need to provide this copyright notice is why 7574f16 added the
`java-source-utils.jar --doc-*` options, so that the above notice
could be appropriate inserted.

The problem is that `generator` only emits the copyright notice when
`generator --doc-comment-verbosity=full` is used, and "full" output
is incomplete (many constructs aren't supported) and buggy (many
constructs result in "invalid" member references which may cause
[breakage with `mdoc update`][1] [^1]).

Square this circle by adding a new
`generator --doc-comment-verbosity=intellisense+extraremarks` value,
which emits "intellisense" *plus* the "extra remarks" output, which
includes the copyright notice and documentation links.

This allows us to have the benefits of intellisense (faster,
semantically correct output) and *also* retain the extras.

[0]: https://github.com/xamarin/android-api-docs
[1]: https://discord.com/channels/732297728826277939/732297837953679412/796506764438142978

[^1]: `mdoc update` for "full" output will eventually fail with:

          System.Xml.XPath.XPathException: 'altmember[@cref='!:Java.Interop.Tools.JavaSource.SourceJavadocToXmldocGrammar+<ToXmlContent>d__9 and
          <c>
            <see cref="#EXTRA_EMBEDDED_SUBSCRIPTION_SMDX_REASON_CODE" />
          </c>

          In the case where ErrorCode contains a value of 0, it means it's an unknown error. E.g Intent
          only contains <c>
            <see cref="#OPERATION_DOWNLOAD" />
          </c> and ErrorCode is 0 implies this is an unknown
          Download error.']' has an invalid token.
            at MS.Internal.Xml.XPath.XPathParser.CheckToken (MS.Internal.Xml.XPath.XPathScanner+LexKind t) [0x00023] in <6062976fd2cb473f91f94556758db404>:0
          …

      This happens because the generated `<altmember/>` is bad.

Author: jonpryor

src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocParser.cs

@@ -25,6 +25,7 @@ internal enum ImportJavadoc {
 		SerialTag           = 1 << 8,
 		SinceTag            = 1 << 9,
 		VersionTag          = 1 << 10,
+		ExtraRemarks        = 1 << 11,
 	}
 
 	[Flags]
@@ -41,12 +42,16 @@ public enum XmldocStyle {
 			| ImportJavadoc.SerialTag
 			| ImportJavadoc.SinceTag
 			| ImportJavadoc.VersionTag
+			| ImportJavadoc.ExtraRemarks
 			,
 		IntelliSense = ImportJavadoc.Summary
 			| ImportJavadoc.ExceptionTag
 			| ImportJavadoc.ParamTag
 			| ImportJavadoc.ReturnTag
 			,
+		IntelliSenseAndExtraRemarks = IntelliSense
+			| ImportJavadoc.ExtraRemarks
+			,
 	}
 
 	public class SourceJavadocToXmldocParser : Irony.Parsing.Parser {
@@ -102,6 +107,9 @@ IEnumerable<XNode> CreateParseIterator (ParseTree parseTree)
 						(info.Remarks.Count > 0 || ExtraRemarks?.Length > 0)) {
 					yield return new XElement ("remarks", info.Remarks, ExtraRemarks);
 				}
+				else if (style.HasFlag (ImportJavadoc.ExtraRemarks) && ExtraRemarks?.Length > 0) {
+					yield return new XElement ("remarks", ExtraRemarks);
+				}
 				foreach (var n in info.Returns) {
 					yield return n;
 				}

tools/generator/CodeGeneratorOptions.cs

@@ -211,6 +211,7 @@ static CodeGenerationTarget ParseCodeGenerationTarget (string value)
 
 		static XmldocStyle ParseXmldocStyle (string style) => style?.ToLowerInvariant () switch {
 			"intellisense" => XmldocStyle.IntelliSense,
+			"intellisense+extraremarks" => XmldocStyle.IntelliSenseAndExtraRemarks,
 			"full" => XmldocStyle.Full,
 			_ => XmldocStyle.Full,
 		};

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

@@ -80,7 +80,7 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style)
 
 		static XElement[] GetExtra (XElement element, XmldocStyle style, string declaringJniType, string declaringMemberName, string declaringMemberJniSignature)
 		{
-			if (!style.HasFlag (XmldocStyle.Full))
+			if (!style.HasFlag (XmldocStyle.IntelliSenseAndExtraRemarks))
 				return null;
 
 			XElement javadocMetadata    = null;