From 3aad3468b6b7108e0f9d5beebf6c2d4e00257024 Mon Sep 17 00:00:00 2001 From: Peter Collins Date: Wed, 10 Nov 2021 18:32:24 -0500 Subject: [PATCH] [generator] Improve Javadoc remarks on properties Fixes: https://github.com/xamarin/java.interop/issues/905 Property getters and setters will no longer automatically include copyright info in their generated `` elements. Instead, this copyright data will be appended to the `` element after `` merging is complete. The custom `` and `` merging that happens for properties will now also use Nodes instead of DescendantNodes to avoid content duplication. --- .../JavadocInfo.cs | 21 +++++++++++++------ .../JavadocFixups.cs | 4 ++-- .../generator/SourceWriters/BoundProperty.cs | 16 +++++++++++--- 3 files changed, 30 insertions(+), 11 deletions(-) diff --git a/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs b/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs index 636382f4e..cc105825f 100644 --- a/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs +++ b/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 extra = null; + IEnumerable 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 (); 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) diff --git a/tools/generator/Java.Interop.Tools.Generator.Transformation/JavadocFixups.cs b/tools/generator/Java.Interop.Tools.Generator.Transformation/JavadocFixups.cs index fb751e455..1da748c16 100644 --- a/tools/generator/Java.Interop.Tools.Generator.Transformation/JavadocFixups.cs +++ b/tools/generator/Java.Interop.Tools.Generator.Transformation/JavadocFixups.cs @@ -70,11 +70,11 @@ static void AddJavadoc (GenBase type, Dictionary 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); } } diff --git a/tools/generator/SourceWriters/BoundProperty.cs b/tools/generator/SourceWriters/BoundProperty.cs index 24a627aff..23bf25cf1 100644 --- a/tools/generator/SourceWriters/BoundProperty.cs +++ b/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 ()); } } }