Skip to content

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