Repository navigation
Clarify PlatformException code, message, and details docs - #194293
Open
Arefin-Himu wants to merge 1 commit into
Open
Arefin-Himu wants to merge 1 commit into
Arefin-Himu wants to merge 1 commit into
Conversation
The PlatformException field docs did not explain where the error code comes from, why the message can be null, or which values the details can hold, and the three "See also" entries each had an extra comma. Document that the error code and details are supplied by the code that reports the error, that any String can be used as an error code, that a message is optional, and that details must be supported by the channel's MethodCodec (for the default StandardMethodCodec, the values documented with StandardMessageCodec). Remove the extra commas. Part of flutter#74352
github-actions
Bot
added
the
framework
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates the documentation comments for the PlatformException class in message_codec.dart by adjusting punctuation and adding descriptions for the code, message, and details fields. A review comment suggests using square brackets instead of backticks for StandardMethodCodec and StandardMessageCodec to enable proper Dartdoc cross-linking.
Comment on lines
+128
to
+130
| /// value must be supported by the [MethodCodec] used by the channel; for the | ||
| /// default `StandardMethodCodec`, the supported values are documented with | ||
| /// `StandardMessageCodec`. |
Contributor
There was a problem hiding this comment.
To ensure proper API documentation generation and cross-linking, refer to StandardMethodCodec and StandardMessageCodec using square brackets (e.g., [StandardMethodCodec] and [StandardMessageCodec]) instead of backticks. This allows Dartdoc to generate hyperlinks to their respective documentation.
Suggested change
| /// value must be supported by the [MethodCodec] used by the channel; for the | |
| /// default `StandardMethodCodec`, the supported values are documented with | |
| /// `StandardMessageCodec`. | |
| /// value must be supported by the [MethodCodec] used by the channel; for the | |
| /// default [StandardMethodCodec], the supported values are documented with | |
| /// [StandardMessageCodec]. |
References
- Introduce terms: Assume the reader does not know everything. Link to definitions. (link)
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
1 participant
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.
Clarifies the
PlatformExceptionAPI documentation inpackages/flutter/lib/src/services/message_codec.dart. This contribution changes documentation comments only and does not alter runtime behavior.The changes improve the documentation in three areas:
code: Explains that the error code is supplied by the code reporting the error and that anyStringcan be used.message: Clarifies that the reporting code is not required to provide a message.details: Explains that the details are supplied by the reporting code and must be supported by the channel'sMethodCodec. For the defaultStandardMethodCodec, it refers readers to the supported values documented withStandardMessageCodec.The change also removes the extra comma from each of the three relevant “See also” entries, as requested in [#74352](#74352).
Scope: This contribution addresses only part of the issue. It does not add examples or fully address when
messageorstacktraceshould be null; those aspects remain outside this change.Validation
git diff --checkdart format --output=none --set-exit-if-changeddart analyze --fatal-infosonmessage_codec.dart, with no issues found.dev/bots/analyze.dart, the full test suite, and the full documentation build.master.Pre-launch Checklist
///).If you need help, consider asking for advice in the #hackers-new channel on [Discord].
If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.
Note: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the
gemini-code-assistbot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.