[jnigen] Add javadoc.io fallback for missing Javadoc by Siya-05 · Pull Request #3586 · dart-lang/native

Siya-05 · 2026-08-26T04:34:33Z

Description

Adds a javadoc.io fallback link to generated Dart methods when Javadoc is not
available.

JNIgen already preserves Javadoc when it is available from the source backend.
When Javadoc is missing and a single Maven dependency is configured, this
change instead adds a link to that dependency's documentation on javadoc.io.

This follows the approach discussed in #2819 and avoids downloading or parsing
Javadoc HTML.

Related Issues

Fixes #2819

PR Checklist

I’ve reviewed the contributor guide and applied the relevant portions to this PR.
I've run dart tool/ci.dart --all locally and resolved all issues identified. This ensures the PR is formatted, has no lint errors, and ran all code generators. This applies to the packages part of the toplevel pubspec.yaml workspace.
All existing and new tests are passing. I added new tests to check the change I am making.
The PR is actually solving the issue. PRs that don't solve the issue will be closed. Please be respectful of the maintainers' time. If it's not clear what the issue is, feel free to ask questions on the GitHub issue before submitting a PR.
I have updated CHANGELOG.md for the relevant packages. (Not needed for small changes such as doc typos).
I have updated the pubspec package version if necessary.

Siya-05 · 2026-08-27T01:04:53Z

Fixed CI issues by updating the test import and formatting.

liamappelbe

You've got some merge related analysis errors. Try syncing to head.

liamappelbe · 2026-08-27T03:13:58Z

    });
  });
+
+  test('generates javadoc.io fallback when method Javadoc is missing',


Since this test runs the entire pipeline, it would be easier to add your test to an existing integration test, such as jackson_core_test. Does your change affect those bindings at all?

Yes, it does. I regenerated the jackson_core_test bindings and moved the coverage there. The fallback links are now generated for methods without Javadocs.

Siya-05 · 2026-08-31T01:42:27Z

Hey @liamappelbe,
I’ve pushed the jackson_core_test changes now. Could you rerun the tests on the latest commit when you get a chance?

liamappelbe · 2026-09-01T01:49:17Z


+  String? _mavenJavadocUrl() {


This function only depends on the config. Could its result be cached, and only executed once per run?

liamappelbe · 2026-09-01T01:50:36Z

+      final url = _mavenJavadocUrl();
+      if (url != null) {
+        s.writeln('  ///');
+        s.writeln('  /// See the [Java documentation]($url).');


Ideally this would link to the documentation of the method, rather than just the top level documentation URL. Can we construct the method's URL from this base URL?

Siya-05 · 2026-09-01T19:15:04Z

I looked into constructing method-specific links. One issue is that the Jackson integration test uses jackson-core:2.13.4, whose Javadocs don't appear to be available on javadoc.io, so I tested the URL construction against 2.13.5.

The /static/ class pages work, but that version uses the older Javadoc anchor format (e.g. #getCodec-- and #enabledIn-int-) rather than #getCodec() / #enabledIn(int).

Should I generate method-specific /static/ links using this anchor format, or keep the artifact-level link since the format can depend on the Javadoc/doclet version?

liamappelbe · 2026-09-02T00:39:43Z

The nice thing about the anchors is that if they don't work, at least the user still lands on the correct page for the class. And landing on the class page is better than just being directed to the top level page for the entire library.

So I think under that link format, the link to the class page will usually work, and the link to the specific method will often work (but falls back to the class page if not). That would be a good user experience.

Siya-05 · 2026-09-02T05:37:07Z

I pushed an update that caches the Maven Javadoc base URL and constructs class/method-specific links. I also bumped the Jackson integration fixture to 2.13.5 so its class pages are available on javadoc.io.

Method anchor formats differ across Javadoc versions, so the method fragment is best-effort, while the class page remains a reliable fallback as you described. Let me know if you’d prefer a different anchor strategy.

Siya-05 · 2026-09-03T17:19:46Z

Fixed the Jackson integration test dependency version mismatch (2.13.5 → 2.13.4) to match jnigen.yaml.

liamappelbe

Looks good. Can you just add a changelog entry? This would be version 1.0.1-wip

Siya-05 · 2026-09-04T03:35:29Z

Added the 1.0.1-wip changelog entry.

liamappelbe · 2026-09-07T02:53:40Z

Sorry, should have been more specific. You'll also need to bump the version in the pubspec.yaml to 1.0.1-wip

Siya-05 · 2026-09-07T12:26:57Z

I've bumped the version in pubspec.yaml to 1.0.1-wip. I also noticed the comment there says to keep it in sync with the version constant in dart_generator.dart, which is currently 1.0.0. Should I bump that to 1.0.1 as well?

liamappelbe · 2026-09-07T23:38:29Z

I've bumped the version in pubspec.yaml to 1.0.1-wip. I also noticed the comment there says to keep it in sync with the version constant in dart_generator.dart, which is currently 1.0.0. Should I bump that to 1.0.1 as well?

Yeah. That'll also mean that all the tests and examples need to be regenerated. It's a bit of a pain, but there's a script that does it all: tool/regenerate_all_bindings.dart. See how you go with it. If you run into issues, I can regenerate the bindings myself.

Siya-05 · 2026-09-08T04:34:27Z

I ran tool/regenerate_all_bindings.dart, and noticed that the Jackson bindings regenerate with 2.13.4 Javadoc links because both generate.dart and jnigen.yaml still use jackson-core:2.13.4.

Since the 2.13.4 Javadocs aren't available on javadoc.io, should I bump the Jackson integration fixture to 2.13.5 in both places and regenerate the bindings?

liamappelbe · 2026-09-09T00:03:33Z

Yeah, feel free to bump the version. I don't think v2.13.4 was chosen for any particular reason

Siya-05 · 2026-09-09T03:54:21Z

Bumped the version and regenerated the bindings/examples. Also updated the Jackson fixture to 2.13.5. Tests pass locally.

liamappelbe · 2026-09-09T04:18:29Z

Great job. Just one more thing to regen, jni_flutter: https://github.com/dart-lang/native/actions/runs/34308764825/job/102331701800?pr=3586

Siya-05 · 2026-09-09T04:27:55Z

Done, regenerated jni_flutter as well. Thanks!

liamappelbe · 2026-09-09T04:28:38Z

Sorry about the hassle and noise. Filed #3624 to make our tests slightly less strict about this.

Siya-05 · 2026-09-09T04:52:06Z

No worries! Happy to learn more about the codebase along the way :)

@js

…, web, webdriver Revisions updated by `dart tools/rev_sdk_deps.dart`. core (https://github.com/dart-lang/core/compare/773de9d..7e8caaf): 7e8caafa Thu Sep 10 12:51:06 2026 +0200 Jonas Finnemann Jensen Fix doc comment in FixedDateTimeFormatter (dart-lang/core#998) 0fbe0cc3 Thu Sep 3 16:26:19 2026 -0700 Nate Bosch Mark Context and Style as final (dart-lang/core#995) 1f563bb2 Tue Sep 1 21:54:29 2026 +0000 dependabot[bot] Bump the github-actions group with 5 updates (dart-lang/core#996) b80e4885 Fri Aug 28 12:18:12 2026 +0200 Lasse R.H. Nielsen Release package:platform 3.2 (dart-lang/core#994) 9727aadc Wed Aug 26 09:34:02 2026 -0700 Nate Bosch Add new lints (dart-lang/core#989) dartdoc (https://github.com/dart-lang/dartdoc/compare/2737669..df2f2cd): df2f2cde Tue Sep 8 11:09:41 2026 +0200 dependabot[bot] Bump analyzer_testing from 0.3.4 to 0.4.1 (dart-lang/dartdoc#4282) b028f551 Tue Sep 1 18:56:04 2026 +0000 dependabot[bot] Bump the github-actions group with 2 updates (dart-lang/dartdoc#4281) ecosystem (https://github.com/dart-lang/ecosystem/compare/cda8bd5..1bdafd8): 1bdafd8 Wed Sep 2 16:31:27 2026 -0700 Nate Bosch Tighten workflow for posting PR comments (dart-lang/ecosystem#451) fc3dd9a Mon Aug 31 11:38:33 2026 -0700 Kevin Moore fix(firehose): update existing publishing PR comments when no packages are ready to publish (dart-lang/ecosystem#449) e0a78b4 Mon Aug 31 11:12:56 2026 -0700 Kevin Moore fix(firehose): bump dependency_validator pinned hash to 5.0.6 (dart-lang/ecosystem#450) 60fca9f Tue Aug 25 16:31:57 2026 -0700 Kevin Moore Condense firehose package publishing table in PR validation (dart-lang/ecosystem#445) b79f68c Mon Aug 24 05:47:23 2026 -0700 Kevin Moore chore(health): remove 3rd-party coveralls action dependency (dart-lang/ecosystem#446) http (https://github.com/dart-lang/http/compare/a9176ac..066e158): 066e158 Wed Sep 9 17:15:24 2026 +0200 Eve Chen Skip chunked framing when contentLength is null (dart-lang/http#1970) a6145c3 Wed Sep 9 09:26:05 2026 +1000 Liam Appelbe [cupertino_http] Migrate to FFIgen 22 (dart-lang/http#1986) 92b20d1 Fri Sep 4 10:29:18 2026 -0700 Brian Quinlan test(conformance): HEAD with content-length set (dart-lang/http#1979) bb553a6 Fri Sep 4 11:40:41 2026 +1000 Liam Appelbe [cronet_http] Migrate to JNIgen v1 and use the Dart config API (dart-lang/http#1980) deacd15 Thu Sep 3 16:09:07 2026 -0700 Brian Quinlan chore(cupertino_http): ready to release 3.1.0 (dart-lang/http#1985) ace65bc Wed Sep 2 17:01:14 2026 -0700 Brian Quinlan ci(cupertino_http): only run iOS tests when run-ios-tests label is present (dart-lang/http#1984) 7a79b45 Wed Sep 2 17:00:49 2026 -0700 Brian Quinlan ci(cupertino_http): enable caching for Flutter SDK and pub dependencies (dart-lang/http#1982) 8dbb44c Wed Sep 2 17:00:19 2026 -0700 Brian Quinlan chore(cupertino_http): migrate ios_test from CocoaPods to Swift Package Manager (dart-lang/http#1983) b815a06 Wed Sep 2 23:55:13 2026 +0200 stwime [cupertino_http] Regenerate bindings with ffigen 21 (dart-lang/http#1975) 0d5bee4 Wed Sep 2 10:50:41 2026 -0700 dependabot[bot] chore(deps): bump the github-actions group across 1 directory with 10 updates (dart-lang/http#1976) 6543145 Mon Aug 24 16:32:07 2026 +0100 Ademola Fadumo feat(http2): add a pooled, multiplexed HTTP/2 http.Client (dart-lang/http#1956) a0d49cb Wed Aug 19 18:22:11 2026 -0700 Brian Quinlan fix(http2): reject server push when disabled (dart-lang/http#1966) 8007c92 Wed Aug 19 17:57:46 2026 -0700 Brian Quinlan fix(http2): reject requests that exceed `SETTINGS_MAX_CONCURRENT_STREAMS` (dart-lang/http#1965) 1827980 Wed Aug 19 17:06:20 2026 -0700 dart-ecosystem-bot[bot] Tidy: package:cupertino_http (dart-lang/http#1968) a24ab46 Wed Aug 19 17:03:03 2026 -0700 Brian Quinlan chore: upgrade to jnigen 0.17.0 (dart-lang/http#1964) 9fa7266 Tue Aug 18 16:35:25 2026 -0700 Kevin Moore chore: harden GitHub Actions workflows against Zizmor findings (dart-lang/http#1971) i18n (https://github.com/dart-lang/i18n/compare/2fd9412..1f5ea2f): 1f5ea2fb Tue Sep 8 13:12:25 2026 +0200 Moritz [intl4x] Add intl4x.brittle_i18n_testing environment define (dart-lang/i18n#1093) native (https://github.com/dart-lang/native/compare/38fe179..84d7eda): 84d7edac0 Wed Sep 9 07:38:19 2026 +0200 Jakob Kordež [ffigen] Resolve unexposed C++ types through their canonical type (dart-lang/native#3608) 7b77c03a9 Wed Sep 9 10:31:06 2026 +0530 Sivapriya [jnigen] Add javadoc.io fallback for missing Javadoc (dart-lang/native#3586) 520d280d1 Wed Sep 9 06:57:16 2026 +0200 Jakob Kordež [ffigen] Treat class declarations like structs, decide C++ class binding by POD-ness (dart-lang/native#3607) 350ed4541 Tue Sep 8 09:55:21 2026 +1000 Liam Appelbe [ffigen] Prepare to publish (dart-lang/native#3620) 2cb086a2f Mon Sep 7 12:15:34 2026 +1000 Liam Appelbe [ffigen] Migrate remaining FFIgen YAML configs (dart-lang/native#3614) dc2937e7c Mon Sep 7 11:07:46 2026 +1000 Liam Appelbe [ffigen] Symbol file imports (dart-lang/native#3617) c69575ce5 Fri Sep 4 04:05:59 2026 +0200 Jakob Kordež [ffigen] Skip C++ methods with unbindable return types (dart-lang/native#3591) 5d6f82d9d Fri Sep 4 08:41:35 2026 +1000 Liam Appelbe [objective_c] Migrate ffigen yaml configs (dart-lang/native#3615) ef6db8652 Fri Sep 4 08:41:20 2026 +1000 Liam Appelbe [ffigen] Migrate test YAML configs (dart-lang/native#3613) 9f3dae7e6 Fri Sep 4 08:38:55 2026 +1000 Liam Appelbe [ffigen] Migrate FFIgen configs across the repo (dart-lang/native#3616) 895977bca Fri Sep 4 08:37:25 2026 +1000 Liam Appelbe [jnigen] Prepare to publish v1.0.0 (dart-lang/native#3612) 03f1d8e29 Thu Sep 3 09:13:56 2026 +1000 Liam Appelbe [ffigen] Config cleanup (dart-lang/native#3606) 9560e6c8a Wed Sep 2 09:58:51 2026 +1000 Liam Appelbe [jnigen] Migrate YAMLs to Dart (dart-lang/native#3600) 8836b56ed Tue Sep 1 05:35:52 2026 +0000 dependabot[bot] [infra] Bump the github-actions group with 7 updates (dart-lang/native#3604) 3041c6e88 Tue Sep 1 09:06:17 2026 +1000 Liam Appelbe [jnigen] Little bits of cleanup (dart-lang/native#3599) c4af7b839 Tue Sep 1 09:01:03 2026 +1000 Liam Appelbe [jni_flutter] Bump kotlin version (dart-lang/native#3598) ff508aeb2 Thu Aug 27 12:30:15 2026 +0200 Daco Harkes [code_assets] [native_toolchain_c] Add arm64e (dart-lang/native#3589) f914da89c Thu Aug 27 05:37:06 2026 +0200 Jakob Kordež [ffigen] Fix infinite recursion when parsing cyclic C++ class references (dart-lang/native#3584) 0f05f8895 Thu Aug 27 11:36:48 2026 +1000 Liam Appelbe [ffigen][jnigen] Clean up dartdoc categories (dart-lang/native#3587) ae80f0dfa Wed Aug 26 18:23:47 2026 +0200 Alexander Thomas Merge pull request `#3588` from dart-lang/merge-cherry-pick-3581 bcf1529b9 Wed Aug 26 07:51:49 2026 -0700 Brian Quinlan Merge branch 'main' into merge-cherry-pick-3581 bd5e0ff05 Wed Aug 26 14:24:50 2026 +1000 Liam Appelbe [ffigen] Final config cleanup (dart-lang/native#3575) 363e9ae91 Tue Aug 25 14:35:54 2026 -0700 Brian Quinlan Merge remote-tracking branch 'origin/cherry-pick-3581' into merge-cherry-pick-3581 d51c53334 Tue Aug 25 01:07:51 2026 -0700 Brian Quinlan [hooks_runner] use target path separator (dart-lang/native#3581) 7ee7629d6 Tue Aug 25 13:59:24 2026 +0530 Varad Raj Agrawal [native_toolchain_c] Inject FileSystem for file system access (dart-lang/native#3555) shelf (https://github.com/dart-lang/shelf/compare/fb3f931..f36dd68): f36dd68 Tue Sep 1 12:29:24 2026 +0000 dependabot[bot] build(deps): bump dart-lang/setup-dart in the github-actions group (dart-lang/shelf#539) 3dbf65b Thu Aug 27 16:05:14 2026 -0700 Kevin Moore fix(shelf_static): Handle int overflow during byte range parsing (dart-lang/shelf#538) tools (https://github.com/dart-lang/tools/compare/441ff29..682f285): 682f2854 Thu Sep 10 09:08:32 2026 -0700 Keerti Parthasarathy [unified_analytics] Update code to mock `isExternal` in tests. (dart-lang/tools#2594) b09f9a33 Fri Sep 4 11:46:08 2026 -0700 Kevin Moore [api_summary] Support dart:js_interop annotations (@js and @JSExport) (dart-lang/tools#2527) 292130b6 Thu Sep 3 19:27:26 2026 -0700 Kevin Moore [api_summary] Introduce ApiFacet model and migrate package:meta annotations (dart-lang/tools#2526) cacb5a56 Wed Sep 2 10:03:40 2026 +0700 herdiyanitdev fix(markdown): avoid quadratic parse time on long unbroken words (dart-lang/tools#2536) 10ea88d0 Tue Sep 1 10:08:46 2026 -0700 Nate Bosch Remove @internal annotations for now (dart-lang/tools#2576) 3306952a Tue Sep 1 06:11:16 2026 +0000 dependabot[bot] build(deps): bump the github-actions group with 4 updates (dart-lang/tools#2577) 94ee86ed Fri Aug 28 14:54:46 2026 -0700 Kevin Moore feat: export ErrorListener and ErrorCollector from yaml.dart (dart-lang/tools#2551) c7f7a63f Fri Aug 28 12:25:32 2026 -0700 Nate Bosch Prepare to publish packages (dart-lang/tools#2562) 3b3b22c2 Fri Aug 28 09:10:36 2026 +0200 Jonas Finnemann Jensen [extension_discovery] Fixup review comments (dart-lang/tools#2557) web (https://github.com/dart-lang/web/compare/6b84f81..e5c6c02): e5c6c02 Tue Sep 1 06:54:56 2026 +0000 dependabot[bot] Bump the github-actions group with 2 updates (dart-lang/web#574) c4d8884 Thu Aug 20 21:31:53 2026 +0000 dependabot[bot] Bump the github-actions group with 3 updates (dart-lang/web#569) 6d96d9e Thu Aug 20 14:08:47 2026 -0700 Kevin Moore chore: harden GitHub Actions workflows against Zizmor findings (dart-lang/web#568) webdriver (https://github.com/google/webdriver.dart/compare/3a711eb..9b2e87d): 9b2e87d Wed Sep 9 12:55:07 2026 -0700 Kevin Moore ci: align publish workflow and enable direct PR comments (google/webdriver.dart#348) 1da600f Fri Sep 4 11:40:38 2026 -0700 dependabot[bot] Bump the actions group across 1 directory with 3 updates (google/webdriver.dart#347) 0046657 Fri Sep 4 13:10:07 2026 -0400 Nate Biggs Publish version 3.2.0 (google/webdriver.dart#346) [email protected] Change-Id: Ib3be7bf3d3a0c91ebeb01002b7e63fcb86de1f92 TAG=agy CONV=e6fd1c32-ded3-443f-83e5-2e15b4ffaccb Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/544260 Commit-Queue: Johnni Winther <[email protected]> Reviewed-by: Samuel Rawlins <[email protected]> Reviewed-by: Johnni Winther <[email protected]> Auto-Submit: Nate Bosch <[email protected]>

github-actions Bot added the package:jnigen label Aug 26, 2026

liamappelbe self-requested a review August 26, 2026 05:12

liamappelbe reviewed Aug 27, 2026

View reviewed changes

Siya-05 added 2 commits August 27, 2026 13:08

[jnigen] Add javadoc.io fallback for undocumented methods

a84fa58

[jnigen] Fix Javadoc fallback tests and formatting

5c1d7da

Siya-05 force-pushed the jnigen-javadoc-fallback branch from 2105c70 to 5c1d7da Compare August 27, 2026 13:08

[jnigen] Use jackson integration test for javadoc fallback

50f1dea

liamappelbe reviewed Sep 1, 2026

View reviewed changes

jnigen: link fallback Javadocs to methods

d0cc43b

[jnigen] Fix Jackson test dependency version

341a68f

liamappelbe reviewed Sep 4, 2026

View reviewed changes

Comment thread pkgs/jnigen/lib/src/bindings/dart_generator.dart Resolved

[jnigen] Address Javadoc fallback review

b7dcd69

Merge branch 'main' into jnigen-javadoc-fallback

b2302c0

[jnigen] Bump package version to 1.0.1-wip

9c135f3

[jnigen] Bump version and regenerate bindings

ae10aad

[jnigen] Regenerate JNI bindings

c26d25e

github-actions Bot added package:jni package:jni_flutter labels Sep 9, 2026

liamappelbe mentioned this pull request Sep 9, 2026

[jnigen] Relax binding verification test #3624

Closed

liamappelbe added the skip-changelog-check label Sep 9, 2026

fix changelog

b44aea4

liamappelbe approved these changes Sep 9, 2026

View reviewed changes

liamappelbe merged commit 7b77c03 into dart-lang:main Sep 9, 2026
47 checks passed

Hassnaa9 pushed a commit to Hassnaa9/native that referenced this pull request Sep 27, 2026

[jnigen] Add javadoc.io fallback for missing Javadoc (dart-lang#3586)

275a72f

Conversation

Siya-05 commented Aug 26, 2026

Description

Related Issues

PR Checklist

Uh oh!

Siya-05 commented Aug 27, 2026

Uh oh!

liamappelbe left a comment

Choose a reason for hiding this comment

Uh oh!

liamappelbe Aug 27, 2026

Choose a reason for hiding this comment

Uh oh!

Siya-05 Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Siya-05 commented Aug 31, 2026

Uh oh!

liamappelbe Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

liamappelbe Sep 1, 2026

Choose a reason for hiding this comment

Uh oh!

Siya-05 commented Sep 1, 2026

Uh oh!

liamappelbe commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Siya-05 commented Sep 2, 2026

Uh oh!

Siya-05 commented Sep 3, 2026

Uh oh!

liamappelbe left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Siya-05 commented Sep 4, 2026

Uh oh!

liamappelbe commented Sep 7, 2026

Uh oh!

Siya-05 commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

liamappelbe commented Sep 7, 2026

Uh oh!

Siya-05 commented Sep 8, 2026

Uh oh!

liamappelbe commented Sep 9, 2026

Uh oh!

Siya-05 commented Sep 9, 2026

Uh oh!

liamappelbe commented Sep 9, 2026

Uh oh!

Siya-05 commented Sep 9, 2026

Uh oh!

liamappelbe commented Sep 9, 2026

Uh oh!

Siya-05 commented Sep 9, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

liamappelbe commented Sep 2, 2026 •

edited

Loading

Siya-05 commented Sep 7, 2026 •

edited

Loading