API docs are out of date #5200
Labels
Area: Mono.Android
Issues with the Android API binding (Mono.Android.dll).
Milestone
Comments
gaurangnirmal
added
the
Area: Mono.Android
jpobst
changed the title
|
These methods are not accessible from code, too. Giving compilation errors. Even if i am targeting my project to API-29. |
|
Ah, I misunderstood and thought only the documentation was missing. The methods are missing due to a binding issue. I have submitted a PR that fixes the methods here: #5208. |
jonpryor
pushed a commit
that referenced
this issue
Oct 15, 2020
Context: #5200 Several API-29 methods are missing from the `AppOpsManager` class, such as [`AndroidOpsManager.unsafeCheckOp(String, int, String)`][0], because they aren't bound at all: warning BG8800: Unknown parameter type 'Android.App.Admin.WatchForeground' for member 'Android.App.AppOpsManagerStartWatchingMode (string, string, Android.App.Admin.WatchForeground, android.app.AppOpsManager.OnOpChangedListener)'. warning BG8700: Unknown return type 'Android.App.Admin.AppOpsManagerMode' for member 'Android.App.AppOpsManagerUnsafeCheckOp (java.lang.String, int, java.lang.String)'. warning BG8700: Unknown return type 'Android.App.Admin.AppOpsManagerMode' for member 'Android.App.AppOpsManagerUnsafeCheckOpNoThrow (java.lang.String, int, java.lang.String)'. warning BG8700: Unknown return type 'Android.App.Admin.AppOpsManagerMode' for member 'Android.App.AppOpsManagerUnsafeCheckOpRaw (java.lang.String, int, java.lang.String)'. warning BG8700: Unknown return type 'Android.App.Admin.AppOpsManagerMode' for member 'Android.App.AppOpsManagerUnsafeCheckOpRawNoThrow (java.lang.String, int, java.lang.String)'. This happens because the `WatchForeground` and `AppOpsManagerMode` enums exist in the `Android.App` namespace, not the `Android.App.Admin` namespace. Update the method map to point to the correct location for the enumerations types, allowing the methods to be correctly bound. [0]: https://developer.android.com/reference/android/app/AppOpsManager#unsafeCheckOp(java.lang.String,%20int,%20java.lang.String)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Oct 30, 2020
Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus are woefully out of date. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained a `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to extract the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `anddroid-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 2, 2020
Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus are woefully out of date. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained a `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to extract the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `anddroid-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 2, 2020
Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus are woefully out of date. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained a `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to extract the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `anddroid-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 14, 2020
Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus are woefully out of date. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained a `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to extract the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `anddroid-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 14, 2020
Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus are woefully out of date. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained a `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to extract the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `anddroid-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 20, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 21, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 21, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 22, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 22, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 22, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Nov 22, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Dec 7, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. For .NET 6 ("One .NET") integration purposes, provide a default item group of `@(JavaSourceJar)` which includes `**\*-source?.jar` and `**\*-src.jar`. This will allow `dotnet build` of an "Android Java Library Binding" project (`dotnet new android-bindinglib`) to automatically process `.java` source code for documentation translation purposes. Finally, add `Java.Interop.Tools.Generator.dll` to the `Microsoft.Android.Sdk*.nupkg` file, as it is an assembly dependency of `generator.dll`. (Not sure why this didn't previously fail…) [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Dec 8, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. For .NET 6 ("One .NET") integration purposes, provide a default item group of `@(JavaSourceJar)` which includes `**\*-source?.jar` and `**\*-src.jar`. This will allow `dotnet build` of an "Android Java Library Binding" project (`dotnet new android-bindinglib`) to automatically process `.java` source code for documentation translation purposes. Finally, add `Java.Interop.Tools.Generator.dll` to the `Microsoft.Android.Sdk*.nupkg` file, as it is an assembly dependency of `generator.dll`. (Not sure why this didn't previously fail…) [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Dec 10, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. For .NET 6 ("One .NET") integration purposes, provide a default item group of `@(JavaSourceJar)` which includes `**\*-source?.jar` and `**\*-src.jar`. This will allow `dotnet build` of an "Android Java Library Binding" project (`dotnet new android-bindinglib`) to automatically process `.java` source code for documentation translation purposes. Add `Java.Interop.Tools.Generator.dll` to the `Microsoft.Android.Sdk*.nupkg` file, as it is an assembly dependency of `generator.dll`. (Not sure why this didn't previously fail…) Finally, add a new `$(_UseLegacyJavadocImport)` MSBuild property which *disables* use of `java-source-utils.jar` for Javadoc importing, and instead use the previous, legacy, doesn't work on JDK 11, approach of using `javadoc` and HTML parsing. This shouldn't be needed, but just in case it *is* needed… [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Dec 11, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. For .NET 6 ("One .NET") integration purposes, provide a default item group of `@(JavaSourceJar)` which includes `**\*-source?.jar` and `**\*-src.jar`. This will allow `dotnet build` of an "Android Java Library Binding" project (`dotnet new android-bindinglib`) to automatically process `.java` source code for documentation translation purposes. Add `Java.Interop.Tools.Generator.dll` to the `Microsoft.Android.Sdk*.nupkg` file, as it is an assembly dependency of `generator.dll`. (Not sure why this didn't previously fail…) Finally, add a new `$(_UseLegacyJavadocImport)` MSBuild property which *disables* use of `java-source-utils.jar` for Javadoc importing, and instead use the previous, legacy, doesn't work on JDK 11, approach of using `javadoc` and HTML parsing. This shouldn't be needed, but just in case it *is* needed… [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Dec 11, 2020
Fixes: dotnet#4789 Context: dotnet/java-interop#687 Context: dotnet#5200 What do we want? Updated documentation! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via [`tools/javadoc2mdoc`]. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Finally, commit 380e95e, which added support for JDK 11, *broke* support for `@(JavaSourceJar)` when running under JDK 11, as JDK 11's Javadoc HTML output differs from what we expect. With the new `java-source-utils.jar` and `generator --with-javadoc-xml=FILE` infrastructure in place, we can reasonably address this breakage under JDK 11, fixing Issue dotnet#4789: Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. For .NET 6 ("One .NET") integration purposes, provide a default item group of `@(JavaSourceJar)` which includes `**\*-source?.jar` and `**\*-src.jar`. This will allow `dotnet build` of an "Android Java Library Binding" project (`dotnet new android-bindinglib`) to automatically process `.java` source code for documentation translation purposes. Add `Java.Interop.Tools.Generator.dll` to the `Microsoft.Android.Sdk*.nupkg` file, as it is an assembly dependency of `generator.dll`. (Not sure why this didn't previously fail…) Finally, add a new `$(_UseLegacyJavadocImport)` MSBuild property which *disables* use of `java-source-utils.jar` for Javadoc importing, and instead use the previous, legacy, doesn't work on JDK 11, approach of using `javadoc` and HTML parsing. This shouldn't be needed, but just in case it *is* needed… [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to dotnet/java-interop
that referenced
this issue
Jan 4, 2021
Fixes: #642 Context: dotnet/android#4789 Context: dotnet/android#5200 Commit 69e1b80 added `tools/java-source-utils`, which along with b588ef5, can parse Java source code and extract Javadoc comments from Android API-30 sources into an XML file: into an XML file: # API-30 `sources` package contains both `Object.java` and `Object.annotated.java`; # Skip the `.annotated.java` files $ find $HOME/android-toolchain/sdk/platforms/android-30/src/{android,java,javax,org} -iname \*.java \ | grep -v '\.annotated\.' > sources.txt $ java -jar java-source-utils.jar -v \ --source "$HOME/android-toolchain/sdk/platforms/android-30/src" \ --output-javadoc android-javadoc.xml \ @sources.txt What can we *do* with the generated `android-javadoc.xml`? `android-javadoc.xml` contains parameter names, and thus can be used with `class-parse --docspath`; see commit 806082f. What we *really* want to do is make the Javadoc information *useful* to consumers of the binding assembly. This means that we want a C# XML Documentation file for the binding assembly. The most straightforward way to get a C# XML Documentation File is to emit [C# XML Documentation Comments][0] into the binding source code! Add a new `generator --with-javadoc-xml=FILE` option. When specified, `FILE` will be treated as an XML file containing the output from `java-source-utils.jar --output-javadoc` (69e1b80), and all `<javadoc/>` elements within the XML file will be associated with C# types and members to emit, based on the `//@jni-signature` and `//@name` attributes, as appropriate. When the bindings are written to disk, the Javadoc comments will be translated to C# XML Documentation comments, in a "best effort" basis. (THIS WILL BE INCOMPLETE.) To perform the Javadoc-to-C# XML Documentation comments conversion, add a new Irony-based grammar to `Java.Interop.Tools.JavaSource.dll`, in the new `Java.Interop.Tools.JavaSource.SourceJavadocToXmldocParser` type, which parses the Javadoc content and translates to XML. In addition to transforming the Javadoc comments into C# XML documentation comments, we *also* want to provide "upstream information" in the form of: 1. A URL to the corresponding online Javadoc HTML documentation. 2. A copyright notice disclaimer. Allow provision of this information by updating `java-source-utils.jar` to support the new options: --doc-copyright FILE Copyright information for Javadoc. Should be in mdoc(5) XML, to be held within <remarks/>. Stored in //javadoc-metadata/copyright. --doc-url-prefix URL Base URL for links to documentation. Stored in //javadoc-metadata/link/@Prefix. --doc-url-style STYLE STYLE of URLs to generate for member links. Stored in //javadoc-metadata/link/@Style. Supported styles include: - developer.android.com/reference@2020-Nov The new `/api/javadoc-metadata/link@prefix` and `/api/javadoc-metadata/link@style` XML attributes, stored within `java-source-utils.jar --output-javadoc` XML output, allow construction of a URL to the Java member. For example, given: java -jar java-source-utils.jar \ --doc-url-prefix https://developer.android.com/reference \ --doc-url-style developer.android.com/reference@2020-Nov Then `generator` can emit the C# documentation comment for `java.lang.Object.equals(Object)`: /// <format type="text/html"> /// <a href="https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)">Java documentation for <tt>java.lang.Object.equals(java.lang.Object)</tt>.</a> /// </format> The copyright notice disclaimer is supported by `java-source-utils.jar --doc-copyright FILE`; the contents of `FILE` are inserted into the `/api/javadoc-metadata/copyright` element, and will be copied into the output of every C# XML documentation block. Example output is at: * <https://gist.github.com/jonpryor/004f01f4cd5ff32299ff590ba7a2fe0e> Unfortunately, converting Javadoc to C# XML Documentation Comments is not a "zero cost" operation. Add a new `generator --doc-comment-verbosity=STYLE` option to control how "complete" the generated documentation comments are: --doc-comment-verbosity=STYLE STYLE of C# documentation comments to emit. Defaults to `full`. STYLE may be: * `intellisense`: emit <summary>, <param>, <returns>, <exception>. * `full`: plus <remarks>, <altmember>, ... Using `--doc-comment-verbosity=full` will *most* impact build times. TODO: * `SourceJavadocToXmldocParser` doesn't support many constructs. [0]: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc
jonpryor
added a commit
that referenced
this issue
Jan 6, 2021
…5253) Fixes: #4789 Context: dotnet/java-interop@7574f16 Context: #5200 What do we want? Updated documentation! Better Bindings! How do we get that? Uh… Historically, [Xamarin.Android API docs][0] were produced by parsing Android's HTML documentation from `docs-24_r01.zip` and converting it into [**mdoc**(5) documentation][1] via `tools/javadoc2mdoc`. The problem is that Google hasn't released an updated `docs*.zip` package since API-24 (~6 years ago), and thus our documentation is woefully out of date. We could have scraped developer.android.com/reference within that time frame, but web scraping is annoying, and we'd still have to deal with the pain of parsing HTML. There is an alternative, though: with API-30, there is a new `sources` package which contains the Java source code used for the API level, which in turn contains Javadoc source code comments. Previous API levels similarly contained an `android-stubs-src.jar` file which likewise contained Java source code containing Javadoc comments. The new approach is to: 1. Update `build-tools/xaprepare` to install the `sources` package. 2. Use [`java-source-tool.jar`][2] to parse the Java source code, creating an `android-javadoc.xml` file. 3. [Update `generator`][3] to consume `android-javadoc.xml` and convert the Javadocs into [C# XML documentation comments][4]. 4. Update `src/Mono.Android` so that `generator` will emit C# XML doc comments, and then produce a `Mono.Android.xml` file. The result is a `Mono.Android.xml` file which contains imported Android Javadoc documentation, e.g. <doc> <assembly><name>Mono.Android</name></assembly> <members> <member name="T:Java.Lang.Object"> <summary>Class <c>Object</c> is the root of the class hierarchy.</summary> <remarks> <para>Class <c>Object</c> is the root of the class hierarchy. … "Later", `Mono.Android.xml` can then be used alongside [`mdoc update --import=Mono.Android.xml`][5] to update our published API documentation. Generation of `Mono.Android.xml` is disabled by default on CI PR builds, as generating `Mono.Android.xml` increases `src/Mono.Android` build times by an unacceptable amount. With the inclusion of `java-source-tools.jar`, we can now fix the TODO mentioned in commit 380e95e, and re-add support for `@(JavaSourceJar)` when running under JDK 11. Update `Xamarin.Android.Bindings.Core.targets` so that before invoking `generator`, we first run `java-source-utils.jar` on the `@(JavaSourceJar)` files, producing Javadoc XML files. The `<BindingsGenerator/>` task in turn is updated to accept a new `BindingsGenerator.JavadocXml` property, which is converted into a `generator --with-javadoc-xml=FILE` option. The `@(JavaSourceJar)` item group is "extended" to support the following item metadata: * `%(CopyrightFile)`: A path to a file that contains copyright information for the Javadoc contents, which will be appended to all imported documentation. * `%(UrlPrefix)`: A URL prefix to support linking to online documentation within imported documentation. * `%(UrlStyle)`: The "style" of URLs to generate when linking to online documentation. Only one style is currently supported: `developer.android.com/reference@2020-Nov`. For .NET 6 ("One .NET") integration purposes, provide a default item group of `@(JavaSourceJar)` which includes `**\*-source*.jar` and `**\*-src.jar`. This will allow `dotnet build` of an "Android Java Library Binding" project (`dotnet new android-bindinglib`) to automatically process `.java` source code for documentation translation purposes. Add a new `$(AndroidJavadocVerbosity)` MSBuild property, which controls "how much" of the Javadoc comments are converted into C# XML documentation. Supported values are: * `full`: Convert as much Javadoc as possible. * `intellisense`: Only emit XML documentation for IDE-useful constructs: summary, parameters, returns, exceptions. The difference between the two is *build time* impact: `full` takes longer, and thus may not always be desirable. Finally, add a new `$(_UseLegacyJavadocImport)` MSBuild property which *disables* use of `java-source-utils.jar` for Javadoc importing, and instead use the previous, legacy, doesn't work on JDK 11, approach of using `javadoc` and HTML parsing. This shouldn't be needed, but just in case it *is* needed… [0]: https://github.com/xamarin/android-api-docs [1]: http://docs.go-mono.com/?link=man%3amdoc(5) [2]: dotnet/java-interop@69e1b80 [3]: dotnet/java-interop#687 [4]: https://docs.microsoft.com/dotnet/csharp/codedoc [5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Jan 11, 2021
Fixes: dotnet#5200 Context: a7413a2 Context: xamarin/android-api-docs#23 Add a new `UpdateExternalDocumentation` target which: 1. *Rebuilds* `src/Mono.Android` with `$(IncludeAndroidJavadoc)`=True. This produces a `Mono.Anroid.xml` file containing imported API-30 Javadoc. 2. Run `mdoc update --import Mono.Android.xml`, updating the [**mdoc**(5) documentation][0] within `external/android-api-docs/docs/Mono.Android/en` Usage: msbuild /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj This process takes ~65 minutes on my machine. Note: This uses the [mdoc NuGet package][1]. [0]: http://docs.go-mono.com/?link=man%3amdoc(5) [1]: https://www.nuget.org/packages/mdoc/
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Jan 12, 2021
Fixes: dotnet#5200 Context: a7413a2 Context: xamarin/android-api-docs#23 Context: https://review.docs.microsoft.com/en-us/engineering/projects/reference/dotnet/mdoc Add a new `UpdateExternalDocumentation` target which: 1. *Rebuilds* `src/Mono.Android` with `$(IncludeAndroidJavadoc)`=True. This produces a `Mono.Anroid.xml` file containing imported API-30 Javadoc. This *also* produces the log file `src/Mono.Android/UpdateExternalDocumentation-{TIME}.binlog`, which contains the build output for the rebuild. 2. Runs `mdoc update --import Mono.Android.xml --use-docid`, updating the [**mdoc**(5) documentation][0] within `external/android-api-docs/docs/Mono.Android/en` The `--use-docid` flag is needed for integration with the documentation infrastructure. Usage: msbuild /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj This process takes ~60 minutes on my machine. Note: This uses the [mdoc NuGet package][1]. [0]: http://docs.go-mono.com/?link=man%3amdoc(5) [1]: https://www.nuget.org/packages/mdoc/
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Jan 13, 2021
Fixes: dotnet#5200 Context: a7413a2 Context: xamarin/android-api-docs#23 Context: https://review.docs.microsoft.com/en-us/engineering/projects/reference/dotnet/mdoc Add a new `UpdateExternalDocumentation` target which: 1. *Rebuilds* `src/Mono.Android` with `$(IncludeAndroidJavadoc)`=True. This produces a `Mono.Anroid.xml` file containing imported API-30 Javadoc. This *also* produces the log file `src/Mono.Android/UpdateExternalDocumentation-{TIME}.binlog`, which contains the build output for the rebuild. 2. Runs `mdoc update --import Mono.Android.xml --use-docid`, updating the [**mdoc**(5) documentation][0] within `external/android-api-docs/docs/Mono.Android/en` The `--use-docid` flag is needed for integration with the documentation infrastructure. Usage: msbuild /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj This process takes ~60 minutes on my machine. Note: This uses the [mdoc NuGet package][1]. [0]: http://docs.go-mono.com/?link=man%3amdoc(5) [1]: https://www.nuget.org/packages/mdoc/
jonpryor
added a commit
to jonpryor/xamarin-android
that referenced
this issue
Jan 14, 2021
Fixes: dotnet#5200 Context: a7413a2 Context: xamarin/android-api-docs#23 Context: https://review.docs.microsoft.com/en-us/engineering/projects/reference/dotnet/mdoc Add a new `UpdateExternalDocumentation` target which: 1. *Rebuilds* `src/Mono.Android` with `$(IncludeAndroidJavadoc)`=True. This produces a `Mono.Anroid.xml` file containing imported API-30 Javadoc. This *also* produces the log file `src/Mono.Android/UpdateExternalDocumentation-{TIME}.binlog`, which contains the build output for the rebuild. 2. Runs `mdoc update --import Mono.Android.xml --use-docid`, updating the [**mdoc**(5) documentation][0] within `external/android-api-docs/docs/Mono.Android/en` The `--use-docid` flag is needed for integration with the documentation infrastructure. Usage: msbuild /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj This process takes ~60 minutes on my machine. Note: This uses the [mdoc NuGet package][1]. [0]: http://docs.go-mono.com/?link=man%3amdoc(5) [1]: https://www.nuget.org/packages/mdoc/
jonpryor
added a commit
that referenced
this issue
Sep 29, 2021
Context: a7413a2 Context: #5200 Context: xamarin/android-api-docs#23 Context: https://review.docs.microsoft.com/en-us/engineering/projects/reference/dotnet/mdoc Add a new `UpdateExternalDocumentation` target to `src/Mono.Android/Mono.Android.csproj` which: 1. *Rebuilds* `src/Mono.Android` with `$(IncludeAndroidJavadoc)`=True. This produces a `Mono.Anroid.xml` file containing imported API-30 Javadoc. On macOS, this *also* produces the log file `src/Mono.Android/UpdateExternalDocumentation-{TIME}.binlog`, which contains the build output for the rebuild. 2. Runs `mdoc update --import Mono.Android.xml --use-docid`, updating the [**mdoc**(5) documentation][0] within `external/android-api-docs/docs/Mono.Android/en` The `--use-docid` flag is needed for integration with the documentation infrastructure. Usage: msbuild /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj This process takes ~60 minutes on my machine. Additionally, add a new `RunMdoc` target, which just runs the `mdoc update --import…` command. This is useful for one-off testing. The `UpdateExternalDocumentation` and `RunMdoc` targets also takes an optional `$(DocTypeName)` MSBuild property, which is used to restrict the types that `mdoc update` will update: msbuild /p:DocTypeName=Java.Lang.Object /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj # -or- msbuild /p:DocTypeName=Java.Lang.Object /t:RunMdoc src/Mono.Android/Mono.Android.csproj Note: This uses the [mdoc NuGet package][1]. [0]: http://docs.go-mono.com/?link=man%3amdoc(5) [1]: https://www.nuget.org/packages/mdoc/5.8.0
ghost
locked as resolved and limited conversation to collaborators
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Steps to Reproduce
No documentation found for updated content.
Expected Behavior
unsafeCheckOp(java.lang.String, int, java.lang.String).
unsafeCheckOpNoThrow(java.lang.String, int, java.lang.String).
and documentation regarding it, should be available.
Please refer below link for more info,
https://developer.android.com/reference/android/app/AppOpsManager#public-methods
Actual Behavior
AppOpsManager.CheckOp(java.lang.String, int, java.lang.String).
AppOpsManager.CheckOpNoThrow(java.lang.String, int, java.lang.String).
Found deprecated in latest apis but no updat in documentations or anything regarding it.
Please Refer links for more info.
https://docs.microsoft.com/en-us/dotnet/api/android.app.appopsmanager.checkop?view=xamarin-android-sdk-9
https://docs.microsoft.com/en-us/dotnet/api/android.app.appopsmanager.checkopnothrow?view=xamarin-android-sdk-9
Version Information
Visual Studio v16.7.4
XF v4.8.0.1364
I am targeting my project to API-29.
The text was updated successfully, but these errors were encountered: