Skip to content

[pigeon]: Correct comment references in doc comments - #11129

Merged
auto-submit[bot] merged 2 commits into
flutter:mainfrom
srawlins:comm-refs
Feb 26, 2026
Merged

[pigeon]: Correct comment references in doc comments#11129
auto-submit[bot] merged 2 commits into
flutter:mainfrom
srawlins:comm-refs

Conversation

@srawlins

@srawlinssrawlins commented Feb 26, 2026

Copy link
Copy Markdown
Contributor

Several doc comments had missed comment references or erroneous comment references. Also a few grammar nits are fixed.

  • [Foo] [Bar] is a Markdown reference link, which presents "Foo" text, linking to a reference "Bar". In order to make this link to Foo and Bar, we need a word in between.
  • Prefer referencing a parameter with square brackets rather than backticks in order to allow for static tooling, like hover, rename, etc.

Pre-Review Checklist

  • I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
  • I read the [Tree Hygiene] page, which explains my responsibilities.
  • I read and followed the [relevant style guides] and ran [the auto-formatter].
  • I signed the [CLA].
  • The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
  • I [linked to at least one issue that this PR fixes] in the description above.
  • I followed [the version and CHANGELOG instructions], using [semantic versioning] and the [repository CHANGELOG style], or I have commented below to indicate which documented exception this PR falls under[^1].
  • I updated/added any relevant documentation (doc comments with ///).
  • I added new tests to check the change I am making, or I have commented below to indicate which [test exemption] this PR falls under[^1].
  • All existing and new tests are passing.

gemini-code-assist[bot]
gemini-code-assistBot reviewed Feb 26, 2026
View reviewed changes

@gemini-code-assistgemini-code-assistBot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates documentation comments in packages/pigeon/lib/src/generator_tools.dart. The changes primarily involve correcting comment references to use square brackets for parameters and methods (e.g., [input], [addScoped]) and improving the phrasing of comments for clarity and grammatical correctness. For instance, the documentation for the Indent.format method's trimIndentation parameter has been expanded for better understanding.

@srawlins

srawlins commented Feb 26, 2026

Copy link
Copy Markdown
ContributorAuthor

None of the changes here are to public API comments. Does this require a CHANGELOG note then?

tarrinneal
tarrinneal approved these changes Feb 26, 2026
View reviewed changes

@tarrinnealtarrinneal left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

solid improvements, thank you

@tarrinneal

tarrinneal commented Feb 26, 2026

Copy link
Copy Markdown
Contributor

@stuartmorgan-g more exceptions

@stuartmorgan-g

stuartmorgan-g commented Feb 26, 2026

Copy link
Copy Markdown
Collaborator

version/changelog override: no client-facing effect since these aren't exported.

(The script doesn't do complex analysis so this kind of false positive is expected.)

@stuartmorgan-gstuartmorgan-g added override: no versioning needed Override the check requiring version bumps for most changes override: no changelog needed Override the check requiring CHANGELOG updates for most changes labels Feb 26, 2026
@stuartmorgan-gstuartmorgan-g added the autosubmit Merge PR when tree becomes green via auto submit App label Feb 26, 2026
@auto-submit
auto-submitBot merged commit 6301571 into flutter:mainFeb 26, 2026
81 checks passed
engine-flutter-autoroll added a commit to engine-flutter-autoroll/flutter that referenced this pull request Feb 27, 2026
@engine-flutter-autoroll
6301571e0 [pigeon]: Correct comment references in doc comments (flutt…
ed0ef58
…er/packages#11129)
@engine-flutter-autorollengine-flutter-autoroll mentioned this pull request Feb 27, 2026
Merged
github-merge-queueBot pushed a commit to flutter/flutter that referenced this pull request Feb 27, 2026
@engine-flutter-autoroll
Roll Packages from e1d01695273f to a27d7c50b3ac (8 revisions) (#183009)
a7a950a
flutter/packages@e1d0169...a27d7c5
2026-02-26 srawlins@google.com [pigeon] Tidy GeneratorAdapters to be
const, with getters instead of fields (flutter/packages#11131)
2026-02-26 matt.boetger@gmail.com [webview_flutter] Remove
usesCleartextTraffic (flutter/packages#11124)
2026-02-26 srawlins@google.com [pigeon]: Correct comment references in
doc comments (flutter/packages#11129)
2026-02-26 matt.boetger@gmail.com [webview_flutter_android] Remove
usesCleartextTraffic (flutter/packages#11122)
2026-02-26 engine-flutter-autoroll@skia.org Roll Flutter from
dad6f9d to b31548f (39 revisions) (flutter/packages#11116)
2026-02-26 matt.boetger@gmail.com [espresso] Remove usesCleartextTraffic
(flutter/packages#11125)
2026-02-26 srawlins@google.com [pigeon] Use function types in order to
avoid dynamic calls (flutter/packages#11130)
2026-02-26 stuartmorgan@google.com [shared_preferences] Revert
androidx.datastore:datastore to 1.1.7 (flutter/packages#11128)
If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages-flutter-autoroll
Please CC flutter-ecosystem@google.com on the revert to ensure that a
human
is aware of the problem.
To file a bug in Flutter:
https://github.com/flutter/flutter/issues/new/choose
To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622
Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
xxxOVALxxx pushed a commit to xxxOVALxxx/flutter that referenced this pull request Mar 10, 2026
@engine-flutter-autoroll@xxxOVALxxx
Roll Packages from e1d01695273f to a27d7c50b3ac (8 revisions) (flutte…
d105ff4
…r#183009)
flutter/packages@e1d0169...a27d7c5
2026-02-26 srawlins@google.com [pigeon] Tidy GeneratorAdapters to be
const, with getters instead of fields (flutter/packages#11131)
2026-02-26 matt.boetger@gmail.com [webview_flutter] Remove
usesCleartextTraffic (flutter/packages#11124)
2026-02-26 srawlins@google.com [pigeon]: Correct comment references in
doc comments (flutter/packages#11129)
2026-02-26 matt.boetger@gmail.com [webview_flutter_android] Remove
usesCleartextTraffic (flutter/packages#11122)
2026-02-26 engine-flutter-autoroll@skia.org Roll Flutter from
dad6f9d to b31548f (39 revisions) (flutter/packages#11116)
2026-02-26 matt.boetger@gmail.com [espresso] Remove usesCleartextTraffic
(flutter/packages#11125)
2026-02-26 srawlins@google.com [pigeon] Use function types in order to
avoid dynamic calls (flutter/packages#11130)
2026-02-26 stuartmorgan@google.com [shared_preferences] Revert
androidx.datastore:datastore to 1.1.7 (flutter/packages#11128)
If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages-flutter-autoroll
Please CC flutter-ecosystem@google.com on the revert to ensure that a
human
is aware of the problem.
To file a bug in Flutter:
https://github.com/flutter/flutter/issues/new/choose
To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622
Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
okorohelijah pushed a commit to okorohelijah/packages that referenced this pull request Mar 26, 2026
@srawlins@okorohelijah
[pigeon]: Correct comment references in doc comments (flutter#11129)
3477895
Several doc comments had missed comment references or erroneous comment references. Also a few grammar nits are fixed.
* `[Foo] [Bar]` is a Markdown reference link, which presents "Foo" text, linking to a reference "Bar". In order to make this link to `Foo` and `Bar`, we need a word in between.
* Prefer referencing a parameter with square brackets rather than backticks in order to allow for static tooling, like hover, rename, etc.
## Pre-Review Checklist
mboetger pushed a commit to mboetger/flutter that referenced this pull request Mar 26, 2026
@engine-flutter-autoroll@mboetger
Roll Packages from e1d01695273f to a27d7c50b3ac (8 revisions) (flutte…
320d999
…r#183009)
flutter/packages@e1d0169...a27d7c5
2026-02-26 srawlins@google.com [pigeon] Tidy GeneratorAdapters to be
const, with getters instead of fields (flutter/packages#11131)
2026-02-26 matt.boetger@gmail.com [webview_flutter] Remove
usesCleartextTraffic (flutter/packages#11124)
2026-02-26 srawlins@google.com [pigeon]: Correct comment references in
doc comments (flutter/packages#11129)
2026-02-26 matt.boetger@gmail.com [webview_flutter_android] Remove
usesCleartextTraffic (flutter/packages#11122)
2026-02-26 engine-flutter-autoroll@skia.org Roll Flutter from
dad6f9d to b31548f (39 revisions) (flutter/packages#11116)
2026-02-26 matt.boetger@gmail.com [espresso] Remove usesCleartextTraffic
(flutter/packages#11125)
2026-02-26 srawlins@google.com [pigeon] Use function types in order to
avoid dynamic calls (flutter/packages#11130)
2026-02-26 stuartmorgan@google.com [shared_preferences] Revert
androidx.datastore:datastore to 1.1.7 (flutter/packages#11128)
If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages-flutter-autoroll
Please CC flutter-ecosystem@google.com on the revert to ensure that a
human
is aware of the problem.
To file a bug in Flutter:
https://github.com/flutter/flutter/issues/new/choose
To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622
Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
creatorpiyush pushed a commit to creatorpiyush/packages that referenced this pull request Jun 10, 2026
@srawlins
[pigeon]: Correct comment references in doc comments (flutter#11129)
0fd2c5b
Several doc comments had missed comment references or erroneous comment references. Also a few grammar nits are fixed.
* `[Foo] [Bar]` is a Markdown reference link, which presents "Foo" text, linking to a reference "Bar". In order to make this link to `Foo` and `Bar`, we need a word in between.
* Prefer referencing a parameter with square brackets rather than backticks in order to allow for static tooling, like hover, rename, etc.
## Pre-Review Checklist
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tarrinnealtarrinnealtarrinneal approved these changes
+1 more reviewer
@gemini-code-assistgemini-code-assist[bot]gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

autosubmitMerge PR when tree becomes green via auto submit Appoverride: no changelog neededOverride the check requiring CHANGELOG updates for most changesoverride: no versioning neededOverride the check requiring version bumps for most changesp: pigeon

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@srawlins@tarrinneal@stuartmorgan-g