-
Notifications
You must be signed in to change notification settings - Fork 59
[generator] Improve Javadoc remarks on properties #911
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Fixes: dotnet#905 Property getters and setters will no longer automatically include copyright info in their generated `<remarks>` elements. Instead, this copyright data will be appended to the `<remarks>` element after `<remarks>` merging is complete. The custom `<summary>` and `<remarks>` merging that happens for properties will now also use Nodes instead of DescendantNodes to avoid content duplication.
Here is an example of problematic doc generation before and after these changes: Before: <Docs>
<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 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>
<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>
<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>
<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>Java documentation for <code>android.app.Activity.setRequestedOrientation(int)</code>android.app.Activity.setRequestedOrientation(int).<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>
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><a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a>Android Open Source Project
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><a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a>Creative Commons 2.5 Attribution License.</remarks>
<since version="Added in API level 1" />
<c>ActivityInfo#screenOrientation ActivityInfo.screenOrientation</c>
</Docs> After: <Docs>
<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 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>
<since version="Added in API level 1" />
</Docs> |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes: #905
Property getters and setters will no longer automatically include
copyright info in their generated
<remarks>
elements. Instead, thiscopyright data will be appended to the
<remarks>
element after<remarks>
merging is complete.The custom
<summary>
and<remarks>
merging that happens forproperties will now also use Nodes instead of DescendantNodes to avoid
content duplication.