Skip to content

JavaDoc Integration? #642

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
Closed
jonpryor opened this issue May 5, 2020 · 1 comment · Fixed by #687
Closed

JavaDoc Integration? #642

jonpryor opened this issue May 5, 2020 · 1 comment · Fixed by #687
Assignees
@jonpryor
Labels
enhancement Proposed change to current functionality

Comments

@jonpryor
Copy link
Member

jonpryor commented May 5, 2020

Currently, there is partial -- and not particularly robust -- support for importing JavaDoc documentation into an Assembly.xml documentation file by way of mdoc:

https://github.com/xamarin/xamarin-android/blob/7dab4ee432dcd1e51c52dfe579023fccaf09c471/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Bindings.targets#L345-L383

(This very well may have bit-rotten…)

The above support requires the mdoc utility, but we're not sure of the long term distribution mechanics of mdoc: dotnet/runtime#35852

As an alternate take, once PR #623 is merged, we might be able to instead do the conversion within generator, such that the generated code itself contains C# code comments converted from JavaDoc. This would allow us to use the "normal" csc /doc toolchain, and remove the need for mdoc entirely. (Except for updating https://github.com/xamarin/android-api-docs, but that's a separate concern.)
@jonpryor jonpryor added the enhancement Proposed change to current functionality label May 5, 2020
@jonpryor jonpryor self-assigned this May 5, 2020
@jonpryor
Copy link
Member Author

jonpryor commented Nov 9, 2020

In-progress: #687

@jonpryor jonpryor mentioned this issue Dec 18, 2020
Merged
jonpryor added a commit that referenced this issue Jan 4, 2021
@jonpryor
[generator] Add generator --with-javadoc-xml=FILE support. (#687)
7574f16 
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
@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

@jonpryor jonpryor

Labels
enhancement Proposed change to current functionality
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[generator] Add --with-javadoc-xml=FILE support. jonpryor/java.interop
1 participant
@jonpryor