Skip to content

Commit 087684a

Browse files
authored
[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>
1 parent dcdcce1 commit 087684a

File tree

3 files changed

+30
-11
lines changed

3 files changed

+30
-11
lines changed

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

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,13 @@ public sealed class JavadocInfo {
2222

2323
public XElement[] ExtraRemarks { get; set; }
2424

25+
public XElement[] Copyright { get; set; }
26+
2527
public XmldocStyle XmldocStyle { get; set; }
2628

2729
string MemberDescription;
2830

29-
public static JavadocInfo CreateInfo (XElement element, XmldocStyle style)
31+
public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool appendCopyrightExtra = true)
3032
{
3133
if (element == null) {
3234
return null;
@@ -39,13 +41,16 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style)
3941
string declaringMemberName = desc.DeclaringMemberName;
4042
var declaringMemberJniSignature = desc.DeclaringMemberJniSignature;
4143

42-
XElement[] extra = GetExtra (element, style, declaringJniType, declaringMemberName, declaringMemberJniSignature);
44+
var extras = GetExtra (element, style, declaringJniType, declaringMemberName, declaringMemberJniSignature, appendCopyrightExtra);
45+
XElement[] extra = extras.Extras;
46+
XElement[] copyright = extras.Copyright;
4347

4448
if (string.IsNullOrEmpty (javadoc) && extra == null)
4549
return null;
4650

4751
var info = new JavadocInfo () {
4852
ExtraRemarks = extra,
53+
Copyright = copyright,
4954
Javadoc = javadoc,
5055
MemberDescription = declaringMemberName == null
5156
? declaringJniType
@@ -78,10 +83,10 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style)
7883
return (declaringJniType, declaringMemberName, declaringMemberJniSignature);
7984
}
8085

81-
static XElement[] GetExtra (XElement element, XmldocStyle style, string declaringJniType, string declaringMemberName, string declaringMemberJniSignature)
86+
static (XElement[] Extras, XElement[] Copyright) GetExtra (XElement element, XmldocStyle style, string declaringJniType, string declaringMemberName, string declaringMemberJniSignature, bool appendCopyrightExtra)
8287
{
8388
if (!style.HasFlag (XmldocStyle.IntelliSenseAndExtraRemarks))
84-
return null;
89+
return (null, null);
8590

8691
XElement javadocMetadata = null;
8792
while (element != null) {
@@ -93,6 +98,7 @@ static XElement[] GetExtra (XElement element, XmldocStyle style, string declarin
9398
}
9499

95100
List<XElement> extra = null;
101+
IEnumerable<XElement> copyright = null;
96102
if (javadocMetadata != null) {
97103
var link = javadocMetadata.Element ("link");
98104
var urlPrefix = (string) link.Attribute ("prefix");
@@ -105,9 +111,12 @@ static XElement[] GetExtra (XElement element, XmldocStyle style, string declarin
105111
}
106112
extra = new List<XElement> ();
107113
extra.Add (docLink);
108-
extra.AddRange (javadocMetadata.Element ("copyright").Elements ());
114+
copyright = javadocMetadata.Element ("copyright").Elements ();
115+
if (appendCopyrightExtra) {
116+
extra.AddRange (copyright);
117+
}
109118
}
110-
return extra?.ToArray ();
119+
return (extra?.ToArray (), copyright?.ToArray ());
111120
}
112121

113122
static ApiLinkStyle ParseApiLinkStyle (string style)

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,11 +70,11 @@ static void AddJavadoc (GenBase type, Dictionary<string, XElement> typeJavadocs,
7070
foreach (var property in type.Properties) {
7171
if (property.Getter != null && property.Getter.JavadocInfo == null) {
7272
var getterJavadoc = GetMemberJavadoc (typeJavadoc, "method", property.Getter.JavaName, property.Getter.JniSignature);
73-
property.Getter.JavadocInfo = JavadocInfo.CreateInfo (getterJavadoc?.Parent, style);
73+
property.Getter.JavadocInfo = JavadocInfo.CreateInfo (getterJavadoc?.Parent, style, appendCopyrightExtra: false);
7474
}
7575
if (property.Setter != null && property.Setter.JavadocInfo == null) {
7676
var setterJavadoc = GetMemberJavadoc (typeJavadoc, "method", property.Setter.JavaName, property.Setter.JniSignature);
77-
property.Setter.JavadocInfo = JavadocInfo.CreateInfo (setterJavadoc?.Parent, style);
77+
property.Setter.JavadocInfo = JavadocInfo.CreateInfo (setterJavadoc?.Parent, style, appendCopyrightExtra: false);
7878
}
7979
}
8080

tools/generator/SourceWriters/BoundProperty.cs

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -158,18 +158,28 @@ void AddJavadocs (Property property)
158158
return;
159159

160160
var memberDocs = new XElement ("member");
161+
XElement[] copyrightExtra = null;
161162

162163
if (property.Getter?.JavadocInfo != null) {
163164
memberDocs.Add (property.Getter.JavadocInfo.ParseJavadoc ());
165+
copyrightExtra = property.Getter.JavadocInfo.Copyright;
164166
}
165167

166168
if (property.Setter?.JavadocInfo != null) {
167169
var setterDocs = new XElement ("member", property.Setter.JavadocInfo.ParseJavadoc ());
170+
if (copyrightExtra == null) {
171+
copyrightExtra = property.Setter.JavadocInfo.Copyright;
172+
}
168173

169174
MergeSummary (memberDocs, setterDocs);
170175
MergeRemarks (memberDocs, setterDocs);
171176

172-
memberDocs.Add (setterDocs.DescendantNodes ());
177+
memberDocs.Add (setterDocs.Nodes ());
178+
}
179+
180+
if (copyrightExtra != null) {
181+
var remarks = memberDocs.Element ("remarks");
182+
remarks?.Add (copyrightExtra);
173183
}
174184

175185
JavadocInfo.AddComments (Comments, memberDocs.Elements ());
@@ -187,7 +197,7 @@ static void MergeSummary (XElement mergeInto, XElement mergeFrom)
187197
else if (toContent != null && fromContent != null) {
188198
fromContent.Remove ();
189199
toContent.Add (" -or- ");
190-
toContent.Add (fromContent.DescendantNodes ());
200+
toContent.Add (fromContent.Nodes ());
191201
}
192202
}
193203

@@ -204,7 +214,7 @@ static void MergeRemarks (XElement mergeInto, XElement mergeFrom)
204214
fromContent.Remove ();
205215
toContent.AddFirst (new XElement ("para", "Property getter documentation:"));
206216
toContent.Add (new XElement ("para", "Property setter documentation:"));
207-
toContent.Add (fromContent.DescendantNodes ());
217+
toContent.Add (fromContent.Nodes ());
208218
}
209219
}
210220
}

0 commit comments

Comments
 (0)