Repository navigation
Add the unscoped-doc-reference warning - #4305
Merged
Merged
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new warning, unscoped-doc-reference (disabled by default), which is triggered when dartdoc resolves a comment reference that the analyzer cannot. It updates the markdown processor, model nodes, package graph, runtime stats, and warnings to support tracking and reporting this warning, and adds comprehensive tests. The reviewer suggested ensuring that firstOrNull is properly resolved, either by importing package:collection/collection.dart or using a fallback check, to avoid potential compilation issues.
Comment on lines
+361
to
+362
| var commentData = element.modelNode?.commentData ?? | ||
| element.documentationFrom.firstOrNull?.modelNode?.commentData; |
There was a problem hiding this comment.
The extension getter firstOrNull is used here, but package:collection/collection.dart is not explicitly imported in this file. To ensure compilation succeeds and to follow best practices for explicit imports, please add the import or use a safe fallback like element.documentationFrom.isEmpty ? null : element.documentationFrom.first.
var commentData = element.modelNode?.commentData ??
(element.documentationFrom.isEmpty
? null
: element.documentationFrom.first.modelNode?.commentData);
jonasfj
approved these changes
Oct 26, 2026
szakarias
added a commit
that referenced
this pull request
Oct 28, 2026
Adds an opt-in warning, `doc-reference-target-differs`, for comment references that dartdoc and the analyzer resolve to different elements. The `comment_references` lint cannot see these, because the reference does resolve; only its destination differs. The analyzer's element and dartdoc's target are compared after mapping a prefix to its library and an implicit accessor to its variable, which is what dartdoc links. Mismatches are reported with the usual "inherited from" referrals and counted in the runtime stats. Ignored by default; enable with `warnings: [doc-reference-target-differs]`. Follows #4305. Towards #4283.
copybara-service Bot
pushed a commit
to dart-lang/sdk
that referenced
this pull request
Oct 28, 2026
…est, tools, webkit_inspection_protocol Revisions updated by `dart tools/rev_sdk_deps.dart`. core (https://github.com/dart-lang/core/compare/04da676..d7bd45c): d7bd45c1 Wed Oct 28 13:23:54 2026 +0530 Chandra ObulaReddy [args] Wrap separators to usageLineLength (dart-lang/core#1032) 6903c6c7 Fri Oct 23 20:10:24 2026 +0000 Jonas Finnemann Jensen [crypto] Prepare to publish 3.0.8 (dart-lang/core#1026) 7c1c3700 Fri Oct 23 11:14:15 2026 -0700 Kevin Moore Tighten pull_request_label workflow permissions (dart-lang/core#1029) f01024fc Thu Oct 22 16:31:50 2026 -0700 Kevin Moore [collection] Share Iterable and Set tests across wrapper_test.dart (dart-lang/core#1028) c782eab4 Thu Oct 22 13:25:34 2026 +0200 Jonas Finnemann Jensen Update convert package README and add examples (dart-lang/core#999) dartdoc (https://github.com/dart-lang/dartdoc/compare/c0e19cf..db94437): db94437c Wed Oct 28 11:37:17 2026 +0100 Sarah Zakarias Add the doc-reference-target-differs warning (dart-lang/dartdoc#4306) b6e3980c Tue Oct 27 14:59:21 2026 +0100 Sarah Zakarias Only treat a doc comment as library documentation when it precedes a library directive (dart-lang/dartdoc#4303) 84a0141f Tue Oct 27 11:22:04 2026 +0100 Sarah Zakarias Add the unscoped-doc-reference warning (dart-lang/dartdoc#4305) b25bcd99 Thu Oct 22 15:56:17 2026 +0300 Sergey G. Grekhov Update/replace TODO in co19 tests (dart-lang/dartdoc#4299) 1e9e771e Thu Oct 22 12:18:48 2026 +0300 Sergey G. Grekhov `#4134`. Add more placement tests for `library` directives (dart-lang/dartdoc#4297) 17629ced Wed Oct 21 10:29:05 2026 -0700 Bob Nystrom Use newer function type syntax for parameters. (dart-lang/dartdoc#4290) f5928b1d Wed Oct 21 15:44:39 2026 +0300 Sergey G. Grekhov `#4134`. Add placement tests for enum values (dart-lang/dartdoc#4223) 24ae37f3 Wed Oct 21 11:18:07 2026 +0200 dependabot[bot] Bump test_reflective_loader from 0.4.0 to 0.6.0 (dart-lang/dartdoc#4296) ecosystem (https://github.com/dart-lang/ecosystem/compare/0ab0cfd..24b9ba8): 24b9ba8 Mon Oct 26 18:40:19 2026 -0700 Kevin Moore fix(repo_manage): increment patch version when transitioning to -wip (dart-lang/ecosystem#474) e1d4a04 Fri Oct 23 20:18:20 2026 +0000 dependabot[bot] Bump the github-actions group across 1 directory with 8 updates (dart-lang/ecosystem#473) 4b44357 Fri Oct 23 11:13:26 2026 -0700 Kevin Moore Tighten pull_request_label workflow permissions (dart-lang/ecosystem#472) i18n (https://github.com/dart-lang/i18n/compare/1f5ea2f..4c7b4ad): 4c7b4ad1 Fri Oct 23 11:14:00 2026 -0700 Kevin Moore Tighten pull_request_label workflow permissions (dart-lang/i18n#1113) 899251b1 Thu Oct 8 11:30:18 2026 +0200 Moritz [intl4x] Fix doc comment examples and verify them via {@example} in tests (dart-lang/i18n#1107) 5c8eb9d5 Thu Oct 8 10:27:58 2026 +0200 Moritz [intl4x] Fix YearStyle.withEra on ECMA when length is short or omitted (dart-lang/i18n#1105) b80bb04a Wed Sep 23 14:37:42 2026 +0200 Michael Thomsen Remove experiment flag no longer needed (dart-lang/i18n#1097) 766fd507 Wed Sep 23 13:59:56 2026 +0200 Moritz [intl4x] Mark DisplayNames API as @experimental and trigger CI on PR base edits (dart-lang/i18n#1098) 08de2f6f Fri Sep 18 12:49:50 2026 +0200 Moritz Rev package:intl4x to 1.0.0 and update status to preview (dart-lang/i18n#1088) native (https://github.com/dart-lang/native/compare/3cbe319..e0ca7c6): e0ca7c60f Wed Oct 28 12:08:25 2026 +0100 Michael Goderbauer [infra] Pin ubuntu-24.04 in workflows installing clang-15 (dart-lang/native#3771) eb09430a9 Tue Oct 27 10:43:22 2026 +0100 Michael Goderbauer [jni] Publish v1.1.1 (dart-lang/native#3765) 94b5f4337 Tue Oct 27 10:21:16 2026 +0100 Michael Goderbauer [jnigen] Pin ubuntu-24.04 in CI workflow (dart-lang/native#3766) 74cc078ee Tue Oct 27 09:29:23 2026 +0100 Michael Goderbauer [jni] Add ProGuard consumer rules for Kotlin classes used by suspend functions (dart-lang/native#3756) 0aa672fed Fri Oct 23 11:13:43 2026 -0700 Kevin Moore [infra] Tighten pull_request_label workflow permissions (dart-lang/native#3764) 8b11b6e01 Fri Oct 23 13:38:47 2026 +0200 Michael Goderbauer [jnigen] Bump AGP to 9.1.1 and KGP to 2.4.10 for Flutter beta (dart-lang/native#3758) protobuf (https://github.com/dart-lang/protobuf/compare/a73edc9..1d52301): 1d52301 Wed Oct 28 08:18:02 2026 -0700 Kevin Moore test(protoc_plugin): replace dart:mirrors in reserved_names_test (google/protobuf.dart#1104) shelf (https://github.com/dart-lang/shelf/compare/b66665b..73b2382): 73b2382 Thu Oct 22 10:43:29 2026 -0700 Kevin Moore shelf_router_generator: ignore invalid_use_of_internal_member on RouterEntry (dart-lang/shelf#548) shelf is held back at 73b2382, before dart-lang/shelf#547, because `pkgs/shelf/test/shelf_io_test.dart` now imports the unpublished `package:_shelf_compliance`, which breaks the shared `shelf_tests` target in google3. test (https://github.com/dart-lang/test/compare/d1afeb1..5967927): 5967927e Mon Oct 26 17:50:52 2026 -0700 Nate Bosch Diagnose browser connection failures and time them out with the suite load timeout (dart-lang/test#2788) 0692e8ae Mon Oct 26 16:29:27 2026 -0700 Kevin Moore Remove mirror_matchers.dart from package:matcher (dart-lang/test#2802) da21f85a Fri Oct 23 11:13:38 2026 -0700 Kevin Moore Tighten pull_request_label workflow permissions (dart-lang/test#2804) e18fd112 Thu Oct 22 15:38:51 2026 -0700 Nate Bosch Report tests that pass on retry as flaky (dart-lang/test#2801) b4ef80c0 Fri Oct 23 02:44:25 2026 +0600 Pranta Dutta Fix compact reporter crash when the terminal is too narrow (dart-lang/test#2799) e3a7f2b6 Tue Oct 20 15:51:34 2026 -0700 Nate Bosch Check that web entrypoints don't import VM-only libraries (dart-lang/test#2797) tools (https://github.com/dart-lang/tools/compare/eee87b1..3980dca): 3980dca39 Wed Oct 28 11:43:38 2026 +0100 Jonas Finnemann Jensen [html] Move contributors list from LICENSE to AUTHORS (dart-lang/tools#2733) 2866a7745 Wed Oct 28 11:13:19 2026 +0100 Jonas Finnemann Jensen [extension_discovery] Prepare for v2.1.1 release (dart-lang/tools#2727) 530feb74e Wed Oct 28 13:38:07 2026 +0530 Chandra ObulaReddy [csslib] Fix the aliceblue, antiquewhite and peru color values (dart-lang/tools#2732) d5c210271 Tue Oct 27 15:07:32 2026 -0700 Kevin Moore [source_span] Fix CR/CRLF highlighting, point-span context, and subspan (dart-lang/tools#2634) cbea5b08e Tue Oct 27 15:07:27 2026 -0700 Kevin Moore [string_scanner] Validate error() span bounds and test eager lastSpan (dart-lang/tools#2715) 22fd7a6a8 Tue Oct 27 15:07:20 2026 -0700 Kevin Moore [csslib] Fix parser, analyzer, polyfill, and printer crashes (dart-lang/tools#2638) webkit_inspection_protocol (https://github.com/google/webkit_inspection_protocol.dart/compare/762115a..2c255f2): 2c255f2 Thu Oct 22 14:18:44 2026 -0700 Kevin Moore Remove dart:mirrors and deprecate dom_model.dart and forwarder.dart (google/webkit_inspection_protocol.dart#141) web is held back at 4e60e61, before dart-lang/web#596, because it changes `package:web` signatures (e.g. `innerHTML=`, `parseFromString`, `Worker()`) from `JSAny` to `String` in ways that break callers in google3. Change-Id: Ia4253b35a91d7c05e34fe0e150ea4cb3e6628015 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/569660 Commit-Queue: Nate Bosch <[email protected]> Reviewed-by: Brian Quinlan <[email protected]>
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
No description provided.