Repository navigation
Fix doc comment references that need prefixed doc imports - #193906
Conversation
github-actions
Bot
added
a: tests
![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 adds several @DocImport statements across multiple files in the flutter and flutter_test packages to improve documentation imports. I have no feedback to provide.
|
Warning Gemini encountered an error creating the review. You can try again by commenting |
| /// @docImport 'package:flutter/gestures.dart' as gestures; | ||
| /// @docImport 'package:flutter/rendering.dart'; | ||
| /// @docImport 'package:flutter/scheduler.dart'; | ||
| /// @docImport 'package:flutter/services.dart'; |
There was a problem hiding this comment.
services, widgets and flutter_test are now duplicated?
There was a problem hiding this comment.
Yes, it's a bit annoying. The prefixed import is needed for the library reference (e.g. [widgets]), and the existing plain import for unqualified references like [BuildContext]. To remove the duplication, we'd have to drop the plain import and qualify all those references, e.g. [widgets.BuildContext], and the prefix would then show up in the link text in the generated docs. This already happens with prefixed regular imports ([ui.Rect] renders as ui.Rect), and at some point we'd like to look into how dartdoc renders prefixed references. For now, it's a choice between duplicate imports and prefixed names in the docs, and I'm happy to go with whichever you prefer.
There was a problem hiding this comment.
That is indeed what I was expecting of it. I'm fine with cleaning that up later, so we can unblock enabling the lint first.
There was a problem hiding this comment.
I agree with @navaronbracke, this is fine for now. I expect that referencing the whole library (e.g. [widgets]) in the docs is not that common.
chunhtai
left a comment
chunhtai
left a comment
There was a problem hiding this comment.
I don't think docimport support prefix. There is this warning https://dart.dev/tools/diagnostics/doc_import_cannot_have_prefix
|
They do work on master, though: |
|
I am not sure if there may be some discrepancy between different system. looks like analyzer is ok with import with prefix, not sure if that applies to dart doc. let me double check with dev experience team to see whether this is ok |
|
oh nvm, it is supported now |
Rolls dartdoc from 9.0.9 to 9.0.11. Since analyzer 14.5.0, dartdoc 9.0.9 crashes on comment references through a prefixed doc import; 9.0.11 fixes that. Needed before flutter#193906 can land. Towards flutter#192870.
justinmc
left a comment
justinmc
left a comment
There was a problem hiding this comment.
LGTM 👍 . I think it will be worth it to be able to enable comment_references!
| /// @docImport 'package:flutter/gestures.dart' as gestures; | ||
| /// @docImport 'package:flutter/rendering.dart'; | ||
| /// @docImport 'package:flutter/scheduler.dart'; | ||
| /// @docImport 'package:flutter/services.dart'; |
There was a problem hiding this comment.
I agree with @navaronbracke, this is fine for now. I expect that referencing the whole library (e.g. [widgets]) in the docs is not that common.
|
Golden file changes have been found for this pull request. Click here to view and triage (e.g. because this is an intentional change). If you are still iterating on this change and are not ready to resolve the images on the Flutter Gold dashboard, consider marking this PR as a draft pull request above. You will still be able to view image results on the dashboard, commenting will be silenced, and the check will not try to resolve itself until marked ready for review. For more guidance, visit Writing a golden file test for Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. |
Rolls dartdoc from 9.0.9 to 9.0.11. Since analyzer 14.5.0, dartdoc 9.0.9 crashes on comment references through a prefixed doc import; 9.0.11 fixes that. Needed before flutter#193906 can land. Towards flutter#192870.
…3906) Adds prefixed `@docImport` directives so that doc comment references that need a prefix resolve in Dart scope. This is possible now that https://dart-review.googlesource.com/c/sdk/+/557680 has rolled into Flutter. - 20 library references in `packages/flutter`, `flutter_test`, and `integration_test`, such as `[widgets]` and `[flutter_test]`. - `[ui.Rect]`, `[ui.Size]`, and `[flutter_test.expectLater]` in `dev/`. The generated API docs link these references the same as before. Towards flutter#192870 — enabling the `comment_references` lint.
Adds prefixed
@docImportdirectives so that doc comment references that need a prefix resolve in Dart scope. This is possible now that https://dart-review.googlesource.com/c/sdk/+/557680 has rolled into Flutter.packages/flutter,flutter_test, andintegration_test, such as[widgets]and[flutter_test].[ui.Rect],[ui.Size], and[flutter_test.expectLater]indev/.The generated API docs link these references the same as before.
Towards #192870 — enabling the
comment_referenceslint.