[Java.Interop.Tools.JavaSource] Add {@ docRoot} support#930
Merged
jonpryor merged 1 commit intodotnet:mainfrom Jan 24, 2022
Merged
[Java.Interop.Tools.JavaSource] Add {@ docRoot} support#930jonpryor merged 1 commit intodotnet:mainfrom
jonpryor merged 1 commit intodotnet:mainfrom
Conversation
f350179 to
e9d8b56
Compare
Member
Author
|
This has generated the following docs diff: There are still some issues to sort out. |
e9d8b56 to
6c0b2b2
Compare
6c0b2b2 to
5ab3a89
Compare
Member
Author
|
Latest docs diff for these changes (as compared to a recent partial update for API 32) - https://gist.github.com/pjcollins/355c3acb20c509c00cfffebe30744082 |
Partially fixes: dotnet#907 Support for `{@ docRoot}` has been added, and an additional parser for `<a href/>` elements has been added to convert these to `<see/>` elements.
5ab3a89 to
63575df
Compare
jonpryor
reviewed
Jan 24, 2022
| </remarks> | ||
| </member>", | ||
| IntelliSenseXml = $@"<member> | ||
| <param name=""manifest"">The value of the <see href=""{DocRootPrefixExpected}guide/topics/manifest/manifest-element.html#vcode""><c>android:versionCode</c></see> manifest attribute.</param> |
Contributor
There was a problem hiding this comment.
<see href="…"/> is a valid construct? I wonder when that happened…
Contributor
There was a problem hiding this comment.
Looks like it happened in 2017. Now I feel old. mono/api-doc-tools@fb07047
Contributor
|
WIP commit message: Partially fixes: https://github.com/xamarin/java.interop/issues/907
Context: https://docs.microsoft.com/en-us/dotnet/api/android.app.backup.backupagent.onrestore?view=xamarin-android-sdk-12#Android_App_Backup_BackupAgent_OnRestore_Android_App_Backup_BackupDataInput_System_Int64_Android_OS_ParcelFileDescriptor_
Context: https://docs.microsoft.com/en-us/dotnet/api/android.animation.animatorlisteneradapter.onanimationend?view=xamarin-android-sdk-12#definition
Original support for the [`{@docRoot}` inline Javadoc tag][0] in
commit 7574f166 was a "TODO"; `{@docRoot}` would expand to
`[TODO: @docRoot]`, resulting in documentation containing such
monstrosities as:
> The value of the
> <a href="[TODO: @docRoot]guide/topics/manifest/manifest-element.html#vcode">android:versionCode</a>
> manifest attribute…
Add support for the `{@docRoot}` inline tag, along with grammar
support for `<a href="…">…</a>` elements. This allows:
<a href="{@docRoot}/example/path">description</a>
to be converted into:
<see href="http://example.com/example/path">description</see>
The value of `{@docRoot}` is expanded into
`XmldocSettings.DocRootValue`, which comes from the
`/api/javadoc-metadata/link/@docroot` element in "Javadoc XML"
created by `java-source-utils.jar` (7574f166), via the new
`java-source-utils.jar --doc-root-url URL` option:
java -jar java-source-utils.jar \
--doc-root-url https://developer.android.com/ \
--doc-url-prefix https://developer.android.com/reference \
--doc-url-style developer.android.com/reference@2020-Nov \
…
TODO: Update the [`@(JavaSourceJar)` Build action][1] so that e.g.
`%(JavaSourceJar.DocRootUrl)` item metadata will be used as the
`java-source-utils.jar --doc-root-url` value.
[0]: https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#docRoot
[1]: https://docs.microsoft.com/en-us/xamarin/android/deploy-test/building-apps/build-items#javasourcejar |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context: https://docs.microsoft.com/en-us/dotnet/api/android.app.backup.backupagent.onrestore?view=xamarin-android-sdk-12#Android_App_Backup_BackupAgent_OnRestore_Android_App_Backup_BackupDataInput_System_Int64_Android_OS_ParcelFileDescriptor_
Context: https://docs.microsoft.com/en-us/dotnet/api/android.animation.animatorlisteneradapter.onanimationend?view=xamarin-android-sdk-12#definition
Partially fixes: #907
Support for
{@ docRoot}has been added, and an additionalparser for
<a href/>elements has been added to convertthese to
<see/>elements.