Skip to content

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