Skip to content

[generator] Fix parameter string in ref doc links #935

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
Dec 15, 2021

Conversation

pjcollins
Copy link
Member

Fixes: #931
Fixes: #932

We have a handful of issues in the https://developer.android.com/ links
that are generated for various type members with complex parameters.
Collections, varargs, and generics are some examples of items that are
not translated correctly when generating the parameter portion of the
reference documentation URL.

The javadoc that we generate for Mono.Android contains <parameter/>
elements under all relevant methods. These elements contain attributes
with additional type data; for instance:

    <method jni-return="Landroid/animation/ObjectAnimator;" jni-signature="(Ljava/lang/Object;Landroid/util/Property;Landroid/util/Property;Landroid/graphics/Path;)Landroid/animation/ObjectAnimator;" name="ofFloat" return="android.animation.ObjectAnimator">
      <parameter jni-type="Ljava/lang/Object;" name="target" type="T"/>
      <parameter jni-type="Landroid/util/Property;" name="xProperty" type="android.util.Property&lt;T, java.lang.Float&gt;"/>
      <parameter jni-type="Landroid/util/Property;" name="yProperty" type="android.util.Property&lt;T, java.lang.Float&gt;"/>
      <parameter jni-type="Landroid/graphics/Path;" name="path" type="android.graphics.Path"/>
      <javadoc>
        <![CDATA[Constructs and returns an ObjectAnimator that animates coordinates along a <code>Path</code>
    using two properties. A <code>Path</code></> animation moves in two dimensions, animating
    coordinates <code>(x, y)</code> together to follow the line. In this variation, the
    coordinates are floats that are set to separate properties, <code>xProperty</code> and
    <code>yProperty</code>.

    @param target The object whose properties are to be animated.
    @param xProperty The property for the x coordinate being animated.
    @param yProperty The property for the y coordinate being animated.
    @param path The <code>Path</code> to animate values along.
    @return An ObjectAnimator object that is set up to animate along <code>path</code>.]]>
      </javadoc>
    </method>

Rather than processing the jni-signature attribute of the method, these
parameter elements can be used to produce more reliable type information
for our reference documentation links.

Fixes: dotnet#931
Fixes: dotnet#932

We have a handful of issues in the https://developer.android.com/ links
that are generated for various type members with complex parameters.
Collections, varargs, and generics are some examples of items that are
not translated correctly when generating the parameter portion of the
reference documentation URL.

The javadoc that we generate for Mono.Android contains `<parameter/>`
elements under all relevant methods.  These elements contain attributes
with additional type data; for instance:

    <method jni-return="Landroid/animation/ObjectAnimator;" jni-signature="(Ljava/lang/Object;Landroid/util/Property;Landroid/util/Property;Landroid/graphics/Path;)Landroid/animation/ObjectAnimator;" name="ofFloat" return="android.animation.ObjectAnimator">
      <parameter jni-type="Ljava/lang/Object;" name="target" type="T"/>
      <parameter jni-type="Landroid/util/Property;" name="xProperty" type="android.util.Property&lt;T, java.lang.Float&gt;"/>
      <parameter jni-type="Landroid/util/Property;" name="yProperty" type="android.util.Property&lt;T, java.lang.Float&gt;"/>
      <parameter jni-type="Landroid/graphics/Path;" name="path" type="android.graphics.Path"/>
      <javadoc>
        <![CDATA[Constructs and returns an ObjectAnimator that animates coordinates along a <code>Path</code>
    using two properties. A <code>Path</code></> animation moves in two dimensions, animating
    coordinates <code>(x, y)</code> together to follow the line. In this variation, the
    coordinates are floats that are set to separate properties, <code>xProperty</code> and
    <code>yProperty</code>.

    @param target The object whose properties are to be animated.
    @param xProperty The property for the x coordinate being animated.
    @param yProperty The property for the y coordinate being animated.
    @param path The <code>Path</code> to animate values along.
    @return An ObjectAnimator object that is set up to animate along <code>path</code>.]]>
      </javadoc>
    </method>

Rather than processing the jni-signature attribute of the method, these
parameter elements can be used to produce more reliable type information
for our reference documentation links.
@pjcollins
Copy link
Member Author

The following docs diff is dependent on a few other changes landing in android-api-docs first, but can be used as a reference for these changes:
https://gist.github.com/pjcollins/aea5200cad24c4386f59e3cf79427ef2

@jonpryor jonpryor merged commit d3f0c5c into dotnet:main Dec 15, 2021
@pjcollins pjcollins deleted the fix-androiddev-links branch December 15, 2021 16:09
@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
2 participants