From e0155029574abcb68db22fb514e814676c77cccd Mon Sep 17 00:00:00 2001 From: Jonathan Pryor Date: Wed, 6 Jan 2021 17:48:43 -0500 Subject: [PATCH] [generator] Add `--doc-comment-verbosity=intellisense+extraremarks` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Context: https://github.com/xamarin/xamarin-android/commit/a7413a2389886082c3d3422c50a7e6cc84f43d8f 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 xamarin/xamarin-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. Android platform documentation Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License. The need to provide this copyright notice is why 7574f166 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+d__9 and In the case where ErrorCode contains a value of 0, it means it's an unknown error. E.g Intent only contains 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 `` is bad. --- .../SourceJavadocToXmldocParser.cs | 8 ++++++++ tools/generator/CodeGeneratorOptions.cs | 1 + .../JavadocInfo.cs | 3 ++- 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocParser.cs b/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocParser.cs index 5a0d79ce3..b50d8b514 100644 --- a/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocParser.cs +++ b/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 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; } diff --git a/tools/generator/CodeGeneratorOptions.cs b/tools/generator/CodeGeneratorOptions.cs index cdb4e254f..8a601d4e2 100644 --- a/tools/generator/CodeGeneratorOptions.cs +++ b/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, }; diff --git a/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs b/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs index cfcdb4fc5..b1a0f5ab4 100644 --- a/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs +++ b/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; @@ -254,6 +254,7 @@ static XElement CreateAndroidDocLinkUri (string prefix, string declaringJniType, new XAttribute ("type", "text/html"), new XElement ("a", new XAttribute ("href", new Uri (url.ToString ()).AbsoluteUri), + new XAttribute ("title", "Reference documentation"), "Java documentation for ", new XElement ("tt", java.ToString ()), "."));