Skip to content
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.

Sign up for GitHub

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

Jump to bottom

[Api Docs] Java documentation links are wrong for some ObjectAnimator members #931

Closed
pjcollins opened this issue Dec 10, 2021 · 0 comments · Fixed by #935 or xamarin/android-api-docs#30
Closed

[Api Docs] Java documentation links are wrong for some ObjectAnimator members #931

pjcollins opened this issue Dec 10, 2021 · 0 comments · Fixed by #935 or xamarin/android-api-docs#30
Assignees
@pjcollins

Comments

@pjcollins
Copy link
Member

Context: xamarin/android-api-docs#29
Context: https://github.com/xamarin/android-api-docs/blob/fda1236a384b228b46033fd624854851a87c08df/docs/Mono.Android/en/Android.Animation/ObjectAnimator.xml#L193
Context: https://developer.android.com/reference/android/animation/ObjectAnimator#ofArgb(java.lang.Object,%20java.lang.String,%20int...)

Certain generated Java documentation links are using an array syntax [] when they should be using ....
We also don't seem to be handling overloads fully correctly at least in this case, as the links we generate are the same for both

public static Android.Animation.ObjectAnimator? OfArgb (Java.Lang.Object? target, Android.Util.Property? property, params int[]? values);

and

public static Android.Animation.ObjectAnimator? OfArgb (Java.Lang.Object? target, string? propertyName, params int[]? values);
@pjcollins pjcollins mentioned this issue Dec 10, 2021
Merged
@pjcollins pjcollins self-assigned this Dec 10, 2021
@pjcollins pjcollins changed the title Java documentation links are wrong for some ObjectAnimator types Java documentation links are wrong for some ObjectAnimator members Dec 10, 2021
@pjcollins pjcollins changed the title Java documentation links are wrong for some ObjectAnimator members [Api Docs] Java documentation links are wrong for some ObjectAnimator members Dec 10, 2021
This was referenced Dec 10, 2021
Closed
Merged
pjcollins added a commit to pjcollins/java.interop that referenced this issue Dec 14, 2021
@pjcollins
[generator] Fix parameter string in ref doc links
b1b7156 
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 pjcollins mentioned this issue Dec 14, 2021
Merged
jonpryor pushed a commit that referenced this issue Dec 15, 2021
@pjcollins
[generator] Fix parameter string in ref doc links (#935)
d3f0c5c 
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 XML generated by `java-source-utils` when processing
`android-stubs-src.jar` contains `<parameter/>` elements under all
methods.  The `<parameter/>` 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 `//method/@jni-signature` attribute of the
method, use the `//method/parameter/@type` attribute values to create
more reliable type information for our reference documentation links.

With these changes in place, instead of e.g.

	https://developer.android.com/reference/android/accounts/AccountManager#addAccount(java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle,%20android.app.Activity,%20android.accounts.AccountManagerCallback,%20android.os.Handler)

which doesn't anchor to the intended method documentation, we now emit

	https://developer.android.com/reference/android/accounts/AccountManager#addAccount(java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle,%20android.app.Activity,%20android.accounts.AccountManagerCallback%3Candroid.os.Bundle%3E,%20android.os.Handler)

which *does* anchor to the intended method documentation.
pjcollins added a commit to xamarin/android-api-docs that referenced this issue Dec 15, 2021
@pjcollins
Update docs using dotnet/java-interop@d64087cf (#29)
a7e9149 
Fixes: dotnet/java-interop#933
Context: dotnet/java-interop#931
Context: dotnet/java-interop#932

Changes: dotnet/java-interop@087684a...d64087c

Changes: dotnet/android@aea70ca...05dd813

Changes of note:

  * Includes a bunch of fixes for method overloads.

  * Documentation URLs have been updated to *better* match what the
    Android doc link should be.
    *Note*: these are still not all *correct*; See dotnet/java-interop#931
    and dotnet/java-interop#932.

No new documentation warnings or suggestions have been introduced:

    Total Build Warnings | 1124
    Total Build Suggestions | 902
pjcollins added a commit to xamarin/android-api-docs that referenced this issue Dec 17, 2021
@pjcollins
Update docs using dotnet/java-interop@d3f0c5c
518a7ef 
Fixes: dotnet/java-interop#931
Fixes: dotnet/java-interop#932
Context: dotnet/java-interop@d3f0c5c

Fixes reference documentation URLs for type members with complex
parameters.
pjcollins added a commit to xamarin/android-api-docs that referenced this issue Dec 17, 2021
@pjcollins
Update docs using dotnet/java-interop@d3f0c5c
2378936 
Fixes: dotnet/java-interop#931
Fixes: dotnet/java-interop#932
Context: dotnet/java-interop@d3f0c5c

Fixes reference documentation URLs for type members with complex
parameters.
@pjcollins pjcollins mentioned this issue Dec 17, 2021
Merged
pjcollins added a commit to xamarin/android-api-docs that referenced this issue Dec 20, 2021
@pjcollins
Update docs using dotnet/java-interop@d3f0c5c (#30)
b1743ec 
Fixes: dotnet/java-interop#931
Fixes: dotnet/java-interop#932
Context: dotnet/java-interop@d3f0c5c

Fixes reference documentation URLs for type members with complex
parameters.
pjcollins added a commit to xamarin/android-api-docs that referenced this issue Dec 20, 2021
@pjcollins
Update docs using dotnet/java-interop@d64087cf (#29)
6d6eb07 
Fixes: dotnet/java-interop#933
Context: dotnet/java-interop#931
Context: dotnet/java-interop#932

Changes: dotnet/java-interop@087684a...d64087c

Changes: dotnet/android@aea70ca...05dd813

Changes of note:

  * Includes a bunch of fixes for method overloads.

  * Documentation URLs have been updated to *better* match what the
    Android doc link should be.
    *Note*: these are still not all *correct*; See dotnet/java-interop#931
    and dotnet/java-interop#932.

No new documentation warnings or suggestions have been introduced:

    Total Build Warnings | 1124
    Total Build Suggestions | 902
pjcollins added a commit to xamarin/android-api-docs that referenced this issue Dec 20, 2021
@pjcollins
Update docs using dotnet/java-interop@d3f0c5c (#30)
b67d99b 
Fixes: dotnet/java-interop#931
Fixes: dotnet/java-interop#932
Context: dotnet/java-interop@d3f0c5c

Fixes reference documentation URLs for type members with complex
parameters.
@pjcollins pjcollins mentioned this issue Dec 20, 2021
Merged
pjcollins added a commit to xamarin/android-api-docs that referenced this issue Dec 21, 2021
@pjcollins
Merge pull request #31 from xamarin/dev/pjc/merge-ji-d3f0c5c-live
099ecf9 
Fixes: dotnet/java-interop#931
Fixes: dotnet/java-interop#932
Fixes: dotnet/java-interop#933

Changes of note:

  * Includes a bunch of fixes for method overloads.

  * Documentation URLs have been fixed for type members with complex
     parameters.
davidbritch added a commit to xamarin/android-api-docs that referenced this issue Sep 14, 2022
@shawnwang-ms @pjcollins
@davidbritch @TianqiZhang
Merge main to live (#38)
10da545 
* Update docs using dotnet/java-interop@d64087cf (#29)

Fixes: dotnet/java-interop#933
Context: dotnet/java-interop#931
Context: dotnet/java-interop#932

Changes: dotnet/java-interop@087684a...d64087c

Changes: dotnet/android@aea70ca...05dd813

Changes of note:

  * Includes a bunch of fixes for method overloads.

  * Documentation URLs have been updated to *better* match what the
    Android doc link should be.
    *Note*: these are still not all *correct*; See dotnet/java-interop#931
    and dotnet/java-interop#932.

No new documentation warnings or suggestions have been introduced:

    Total Build Warnings | 1124
    Total Build Suggestions | 902

* Update docs using dotnet/java-interop@d3f0c5c (#30)

Fixes: dotnet/java-interop#931
Fixes: dotnet/java-interop#932
Context: dotnet/java-interop@d3f0c5c

Fixes reference documentation URLs for type members with complex
parameters.

* Master becomes main.

* Update docs using dotnet/java-interop@7716ae53 (#33)

Updates API docs against:

  * dotnet/android@bb2f920
  * dotnet/java-interop@51c3dae

Notable generator improvements include:

  * dotnet/java-interop@4cbc07a
  * dotnet/java-interop@13def0e
  * dotnet/java-interop@32635fd

* Update docs using dotnet/android@ace5f71c (#34)

Imports Google-provided API-31 Javadoc documentation for nested types
that were previously being ignored.

Notable documentation related generator changes:

  * dotnet/java-interop@4b4fedd3: [generator] Process Javadoc for nested types
  * dotnet/java-interop@265ad762: [Java.Interop.Tools.JavaSource] Fix tag parsing errors

Changes in xamarin-android and java.interop:

  * dotnet/android@c6dcefb...ace5f71
  * dotnet/java-interop@7716ae5...032f1e7

* [SEO][Rollout Monikered Canonical]Add URL moniker (#37)

Enable build config to generate canonical URL with moniker

Co-authored-by: Peter Collins <pecolli@microsoft.com>
Co-authored-by: David Britch <davidbritch@users.noreply.github.com>
Co-authored-by: Tianqi Zhang <TianqiZhang@users.noreply.github.com>
@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.
Assignees

@pjcollins pjcollins

Labels
None yet
Projects
None yet
Milestone
No milestone
1 participant
@pjcollins