Skip to content

[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
merged 1 commit into from
Nov 11, 2021

Conversation

pjcollins
Copy link
Member

Fixes: #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.

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.
@pjcollins pjcollins requested a review from jonpryor November 10, 2021 23:44
@pjcollins
Copy link
Member Author

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>

@jonpryor jonpryor merged commit 087684a into dotnet:main Nov 11, 2021
@pjcollins pjcollins deleted the setter-javadoc branch November 11, 2021 03:26
@github-actions github-actions bot locked and limited conversation to collaborators Apr 13, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[Java.Interop.Tools.JavaSource] Fix duplication in Remarks generation for property getter/setters
2 participants