Skip to content

[Javadoc] Merge return values on bound properties #995

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
Jun 16, 2022

Conversation

pjcollins
Copy link
Member

Context: https://developer.android.com/reference/android/animation/Keyframe#setInterpolator(android.animation.TimeInterpolator)

The Java source for Keyframe.setInterpolator incidentally includes a
@return tag, even though the return type is void:

    /**
     * Sets the optional interpolator for this Keyframe. A value of <code>null</code> indicates
     * that there is no interpolation, which is the same as linear interpolation.
     *
     * @return The optional interpolator for this Keyframe.
     */
    public void setInterpolator(TimeInterpolator interpolator) {
        mInterpolator = interpolator;
    }

This causes us to generate multiple <returns> C# doc comment tags on
the Android.Animation.Keyframe.Interpolator property, as the setter
and getter both include the same @return tag:

    /// <summary>Gets the optional interpolator for this Keyframe. -or- Sets the optional interpolator for this Keyframe.</summary>
    /// ...
    /// <returns>The optional interpolator for this Keyframe.</returns>
    /// <returns>The optional interpolator for this Keyframe.</returns>
    public virtual unsafe Android.Animation.ITimeInterpolator? Interpolator {

The mdoc.exe tool does not handle this well, and will continously
append a <value> element on this property every time the tool runs
against our improperly formatted C# doc comments:

    <Docs>
      <summary>Gets the optional interpolator for this Keyframe. -or- Sets the optional interpolator for this Keyframe.</summary>
      <value>The optional interpolator for this Keyframe.</value>
      <value>The optional interpolator for this Keyframe.</value>
      <value>The optional interpolator for this Keyframe.</value>
      ...
      <since version="Added in API level 11" />
    </Docs>

Fix this by attempting to merge returns elements for property getters
and setters.

Context: https://developer.android.com/reference/android/animation/Keyframe#setInterpolator(android.animation.TimeInterpolator)

The Java source for `Keyframe.setInterpolator` incidentally includes a
`@return` tag, even though the return type is void:

    /**
     * Sets the optional interpolator for this Keyframe. A value of <code>null</code> indicates
     * that there is no interpolation, which is the same as linear interpolation.
     *
     * @return The optional interpolator for this Keyframe.
     */
    public void setInterpolator(TimeInterpolator interpolator) {
        mInterpolator = interpolator;
    }

This causes us to generate multiple `<returns>` C# doc comment tags on
the `Android.Animation.Keyframe.Interpolator` property, as the setter
and getter both include the same `@return` tag:

    /// <summary>Gets the optional interpolator for this Keyframe. -or- Sets the optional interpolator for this Keyframe.</summary>
    /// ...
    /// <returns>The optional interpolator for this Keyframe.</returns>
    /// <returns>The optional interpolator for this Keyframe.</returns>
    public virtual unsafe Android.Animation.ITimeInterpolator? Interpolator {

The `mdoc.exe` tool does not handle this well, and will continously
append a `<value>` element on this property every time the tool runs
against our improperly formatted C# doc comments:

    <Docs>
      <summary>Gets the optional interpolator for this Keyframe. -or- Sets the optional interpolator for this Keyframe.</summary>
      <value>The optional interpolator for this Keyframe.</value>
      <value>The optional interpolator for this Keyframe.</value>
      <value>The optional interpolator for this Keyframe.</value>
      ...
      <since version="Added in API level 11" />
    </Docs>

Fix this by attempting to merge `returns` elements for property getters
and setters.
@pjcollins pjcollins requested a review from jonpryor June 16, 2022 20:08
@jonpryor jonpryor merged commit 7716ae5 into dotnet:main Jun 16, 2022
@github-actions github-actions bot locked and limited conversation to collaborators Apr 12, 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.

2 participants