Automate generation of javadocs and create PR with changes

[natke]

Fixed #12389

Staged PR here: https://github.com/natke/onnxruntime/pull/29

[natke]

@Craigacp fyi

[skottmckay]

Is there doco somewhere on how/when this workflow runs? Not sure if it runs automatically or would it be part of the release process?

[Craigacp]

@Craigacp fyi

The generated docs look good. There are a few missing docstrings as it's not pulling them in automatically from overridden methods in the JDK (e.g. places which override toString or close usually pull in the Javadoc from those methods on java.lang.Object and java.lang.AutoCloseable but it's not doing that for some reason), and it's missing a package-info.java in the ai.onnxruntime.providers package. I can add those in another PR once the outstanding JNI PRs are merged in (as there will be conflicts due to some new Java methods in the JNI refactor).

I'm not sure how to feed this into the Gradle javadoc plugin, but it would be nice to have an equivalent overview.html snippet like we have in the Tribuo docs to put a useful description on the Javadoc landing page (e.g. https://github.com/oracle/tribuo/blob/main/Core/src/main/javadoc/overview.html -> the header text above the package list here - https://tribuo.org/learn/4.2/javadoc/).

[natke]

Is there doco somewhere on how/when this workflow runs? Not sure if it runs automatically or would it be part of the release process?

It runs on every push to main/master, so changes are picked up straight away

[skottmckay]

Is there doco somewhere on how/when this workflow runs? Not sure if it runs automatically or would it be part of the release process?

It runs on every push to main/master, so changes are picked up straight away

With this setup do we have any way to see what the API was for a specific release? Or will the doco only be for the very latest code which may not match what the user has? Looks like that's what we do for the other APIs as well though.

[natke]

Is there doco somewhere on how/when this workflow runs? Not sure if it runs automatically or would it be part of the release process?

It runs on every push to main/master, so changes are picked up straight away

With this setup do we have any way to see what the API was for a specific release? Or will the doco only be for the very latest code which may not match what the user has? Looks like that's what we do for the other APIs as well though.

Yes that is what we decided. Given that our APIs are backwards compatible and do not change much for each release, we note in the docs where specific methods and parameters are introduced in which version. There are javadoc annotations for this.

[natke]

@Craigacp fyi

The generated docs look good. There are a few missing docstrings as it's not pulling them in automatically from overridden methods in the JDK (e.g. places which override toString or close usually pull in the Javadoc from those methods on java.lang.Object and java.lang.AutoCloseable but it's not doing that for some reason), and it's missing a package-info.java in the ai.onnxruntime.providers package. I can add those in another PR once the outstanding JNI PRs are merged in (as there will be conflicts due to some new Java methods in the JNI refactor).

I'm not sure how to feed this into the Gradle javadoc plugin, but it would be nice to have an equivalent overview.html snippet like we have in the Tribuo docs to put a useful description on the Javadoc landing page (e.g. https://github.com/oracle/tribuo/blob/main/Core/src/main/javadoc/overview.html -> the header text above the package list here - https://tribuo.org/learn/4.2/javadoc/).

I think (have not confirrmed) that if we added the overview.html into a javadoc dir in our java/src/main dir that this would build this into the generated docs.

[Craigacp]

Ok. I guess I should do a pass to add the @since tags and other things to the Javadoc. I can try adding the overview to see if it works.

[natke]

Ok. I guess I should do a pass to add the @since tags and other things to the Javadoc. I can try adding the overview to see if it works.

Shall we get this PR merged, and make the updates in a subsequent one then?

[Craigacp]

Yes, I don't have time to do that this week.

[natke]

@skottmckay Are you ok to approve the review? Or do you want me to add more comments to the action?