Skip to content

Commit

Permalink
[various] Add missing_code_block_language_in_doc_comment lint to fl…
Browse files Browse the repository at this point in the history
…utter/packages. (flutter#6473)

Adds this Dartdoc-related lint to the flutter repository, in replacement
of the Dartdoc warning (missingCodeBlockLanguage) because it will be
deprecated and removed soon.

flutter/flutter already has this lint as well. Adding to flutter/engine
with flutter/engine#51944.

Lint Proposal: https://github.com/dart-lang/linter/issues/4904

Issue covering future work removing the `// ignore:`s:
flutter/flutter#157620

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [relevant style guides] and ran the
auto-formatter. (Unlike the flutter/flutter repo, the flutter/packages
repo does use `dart format`.)
- [x] I signed the [CLA].
- [x] The title of the PR starts with the name of the package surrounded
by square brackets, e.g. `[shared_preferences]`
- [x] I [linked to at least one issue that this PR fixes] in the
description above.
- [x] I updated `pubspec.yaml` with an appropriate new version according
to the [pub versioning philosophy], or this PR is [exempt from version
changes].
- [x] I updated `CHANGELOG.md` to add a description of the change,
[following repository CHANGELOG style].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/packages/blob/main/CONTRIBUTING.md
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[relevant style guides]:
https://github.com/flutter/packages/blob/main/CONTRIBUTING.md#style
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat
[linked to at least one issue that this PR fixes]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#overview
[pub versioning philosophy]: https://dart.dev/tools/pub/versioning
[exempt from version changes]:
https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages#version-and-changelog-updates
[following repository CHANGELOG style]:
https://github.com/flutter/flutter/wiki/Contributing-to-Plugins-and-Packages#changelog-style
[test-exempt]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#tests
  • Loading branch information
kallentu authored Nov 4, 2024
1 parent abadfb5 commit 79f8b0b
Show file tree
Hide file tree
Showing 37 changed files with 163 additions and 108 deletions.
1 change: 1 addition & 0 deletions analysis_options.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ linter:
# - lines_longer_than_80_chars # not required by flutter style
- literal_only_boolean_expressions
# - matching_super_parameters # blocked on https://github.com/dart-lang/language/issues/2509
- missing_code_block_language_in_doc_comment
- missing_whitespace_between_adjacent_strings
- no_adjacent_strings_in_list
- no_default_cases
Expand Down
3 changes: 2 additions & 1 deletion packages/flutter_migrate/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
## NEXT
## 0.0.1+4

* Adds `missing_code_block_language_in_doc_comment` lint.
* Updates minimum supported SDK version to Flutter 3.19/Dart 3.3.

## 0.0.1+3
Expand Down
4 changes: 2 additions & 2 deletions packages/flutter_migrate/lib/src/base/common.dart
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ String getEnumName(dynamic enumItem) {
/// Rationale:
///
/// Consider the following snippet:
/// ```
/// ```dart
/// try {
/// await foo();
/// ...
Expand All @@ -87,7 +87,7 @@ String getEnumName(dynamic enumItem) {
/// [asyncGuard] is intended to wrap awaited expressions occurring in a `try`
/// block. The behavior described above gives the behavior that users
/// intuitively expect from `await`. Consider the snippet:
/// ```
/// ```dart
/// try {
/// await asyncGuard(() async {
/// var c = Completer();
Expand Down
2 changes: 1 addition & 1 deletion packages/flutter_migrate/lib/src/base/logger.dart
Original file line number Diff line number Diff line change
Expand Up @@ -1125,7 +1125,7 @@ class SpinnerStatus extends AnonymousSpinnerStatus {
/// ```
///
/// yields:
/// ```
/// ```none
/// Usage: app main_command <subcommand>
/// [arguments]
/// ```
Expand Down
2 changes: 1 addition & 1 deletion packages/flutter_migrate/pubspec.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: flutter_migrate
description: A tool to migrate legacy flutter projects to modern versions.
version: 0.0.1+3
version: 0.0.1+4
repository: https://github.com/flutter/packages/tree/main/packages/flutter_migrate
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3Ap%3A%20flutter_migrate
publish_to: none
Expand Down
4 changes: 4 additions & 0 deletions packages/go_router/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
## 14.4.1

- Adds `missing_code_block_language_in_doc_comment` lint.

## 14.4.0

- Adds current state getter on `GoRouter` that returns the current `GoRouterState`.
Expand Down
37 changes: 20 additions & 17 deletions packages/go_router/lib/src/route.dart
Original file line number Diff line number Diff line change
Expand Up @@ -77,15 +77,15 @@ typedef ExitCallback = FutureOr<bool> Function(
/// with the sub routes.
///
/// For example these routes:
/// ```
/// ```none
/// / => HomePage()
/// family/f1 => FamilyPage('f1')
/// person/p2 => PersonPage('f1', 'p2') ← showing this page, Back pops ↑
/// ```
///
/// Can be represented as:
///
/// ```
/// ```dart
/// final GoRouter _router = GoRouter(
/// routes: <GoRoute>[
/// GoRoute(
Expand Down Expand Up @@ -122,12 +122,14 @@ typedef ExitCallback = FutureOr<bool> Function(
/// ),
/// ],
/// );
/// ```
///
/// If there are multiple routes that match the location, the first match is used.
/// To make predefined routes to take precedence over dynamic routes eg. '/:id'
/// consider adding the dynamic route at the end of the routes
/// consider adding the dynamic route at the end of the routes.
///
/// For example:
/// ```
/// ```dart
/// final GoRouter _router = GoRouter(
/// routes: <GoRoute>[
/// GoRoute(
Expand All @@ -145,9 +147,10 @@ typedef ExitCallback = FutureOr<bool> Function(
/// ],
/// );
/// ```
/// In the above example, if /family route is matched, it will be used.
/// else /:username route will be used.
/// ///
///
/// In the above example, if `/family` route is matched, it will be used.
/// else `/:username` route will be used.
///
/// See [main.dart](https://github.com/flutter/packages/blob/main/packages/go_router/example/lib/main.dart)
@immutable
abstract class RouteBase with Diagnosticable {
Expand All @@ -164,7 +167,7 @@ abstract class RouteBase with Diagnosticable {
/// the GoRoute constructor.
///
/// For example:
/// ```
/// ```dart
/// final GoRouter _router = GoRouter(
/// routes: <GoRoute>[
/// GoRoute(
Expand All @@ -183,7 +186,7 @@ abstract class RouteBase with Diagnosticable {
/// redirect takes priority over sub-route's.
///
/// For example:
/// ```
/// ```dart
/// final GoRouter _router = GoRouter(
/// routes: <GoRoute>[
/// GoRoute(
Expand Down Expand Up @@ -327,7 +330,7 @@ class GoRoute extends RouteBase {
/// The path of this go route.
///
/// For example:
/// ```
/// ```dart
/// GoRoute(
/// path: '/',
/// pageBuilder: (BuildContext context, GoRouterState state) => MaterialPage<void>(
Expand All @@ -352,7 +355,7 @@ class GoRoute extends RouteBase {
/// A page builder for this route.
///
/// Typically a MaterialPage, as in:
/// ```
/// ```dart
/// GoRoute(
/// path: '/',
/// pageBuilder: (BuildContext context, GoRouterState state) => MaterialPage<void>(
Expand All @@ -369,7 +372,7 @@ class GoRoute extends RouteBase {
/// A custom builder for this route.
///
/// For example:
/// ```
/// ```dart
/// GoRoute(
/// path: '/',
/// builder: (BuildContext context, GoRouterState state) => FamilyPage(
Expand All @@ -391,7 +394,7 @@ class GoRoute extends RouteBase {
/// This method can be useful it one wants to launch a dialog for user to
/// confirm if they want to exit the screen.
///
/// ```
/// ```dart
/// final GoRouter _router = GoRouter(
/// routes: <GoRoute>[
/// GoRoute(
Expand Down Expand Up @@ -542,7 +545,7 @@ class ShellRouteContext {
/// passed to the /b/details route so that it displays on the root Navigator
/// instead of the ShellRoute's Navigator:
///
/// ```
/// ```dart
/// final GlobalKey<NavigatorState> _rootNavigatorKey =
/// GlobalKey<NavigatorState>();
///
Expand Down Expand Up @@ -601,7 +604,7 @@ class ShellRouteContext {
///
/// For example:
///
/// ```
/// ```dart
/// ShellRoute(
/// builder: (BuildContext context, GoRouterState state, Widget child) {
/// return Scaffold(
Expand Down Expand Up @@ -739,7 +742,7 @@ class ShellRoute extends ShellRouteBase {
/// accomplished by using the method [StatefulNavigationShell.goBranch], for
/// example:
///
/// ```
/// ```dart
/// void _onItemTapped(int index) {
/// navigationShell.goBranch(index: index);
/// }
Expand Down Expand Up @@ -1059,7 +1062,7 @@ typedef ShellNavigationContainerBuilder = Widget Function(BuildContext context,
/// where the List of Widgets represent the Navigators for each branch.
///
/// Example:
/// ```
/// ```dart
/// builder: (BuildContext context, GoRouterState state,
/// StatefulNavigationShell navigationShell) {
/// return StatefulNavigationShell(
Expand Down
2 changes: 1 addition & 1 deletion packages/go_router/lib/src/state.dart
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ class GoRouterState {
///
/// To access GoRouterState from a widget.
///
/// ```
/// ```dart
/// GoRoute(
/// path: '/:id'
/// builder: (_, __) => MyWidget(),
Expand Down
2 changes: 1 addition & 1 deletion packages/go_router/pubspec.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: go_router
description: A declarative router for Flutter based on Navigation 2 supporting
deep linking, data-driven routes and more
version: 14.4.0
version: 14.4.1
repository: https://github.com/flutter/packages/tree/main/packages/go_router
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+go_router%22

Expand Down
3 changes: 2 additions & 1 deletion packages/google_sign_in/google_sign_in/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
## NEXT
## 6.2.2

* Adds `missing_code_block_language_in_doc_comment` lint.
* Updates minimum supported SDK version to Flutter 3.19/Dart 3.3.
* Updates support matrix in README to indicate that iOS 11 is no longer supported.
* Clients on versions of Flutter that still support iOS 11 can continue to use this
Expand Down
2 changes: 1 addition & 1 deletion packages/google_sign_in/google_sign_in/lib/testing.dart
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import 'package:flutter/services.dart' show MethodCall;
///
/// Example usage:
///
/// ```
/// ```dart
/// GoogleSignIn googleSignIn;
/// FakeSignInBackend fakeSignInBackend;
///
Expand Down
2 changes: 1 addition & 1 deletion packages/google_sign_in/google_sign_in/pubspec.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ description: Flutter plugin for Google Sign-In, a secure authentication system
for signing in with a Google account.
repository: https://github.com/flutter/packages/tree/main/packages/google_sign_in/google_sign_in
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+google_sign_in%22
version: 6.2.1
version: 6.2.2

environment:
sdk: ^3.3.0
Expand Down
3 changes: 2 additions & 1 deletion packages/process/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
## NEXT
## 5.0.3

* Adds `missing_code_block_language_in_doc_comment` lint.
* Updates minimum supported SDK version to Flutter 3.19/Dart 3.3.

## 5.0.2
Expand Down
24 changes: 14 additions & 10 deletions packages/process/lib/src/interface/process_manager.dart
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,13 @@ abstract class ProcessManager {
/// The following code uses `start` to grep for `main` in the
/// file `test.dart` on Linux.
///
/// ProcessManager mgr = new LocalProcessManager();
/// mgr.start(['grep', '-i', 'main', 'test.dart']).then((process) {
/// stdout.addStream(process.stdout);
/// stderr.addStream(process.stderr);
/// });
/// ```dart
/// ProcessManager mgr = new LocalProcessManager();
/// mgr.start(['grep', '-i', 'main', 'test.dart']).then((process) {
/// stdout.addStream(process.stdout);
/// stderr.addStream(process.stderr);
/// });
/// ```
///
/// If [mode] is [ProcessStartMode.normal] (the default) a child
/// process will be started with `stdin`, `stdout` and `stderr`
Expand Down Expand Up @@ -130,11 +132,13 @@ abstract class ProcessManager {
/// The following code uses `run` to grep for `main` in the
/// file `test.dart` on Linux.
///
/// ProcessManager mgr = new LocalProcessManager();
/// mgr.run('grep', ['-i', 'main', 'test.dart']).then((result) {
/// stdout.write(result.stdout);
/// stderr.write(result.stderr);
/// });
/// ```dart
/// ProcessManager mgr = new LocalProcessManager();
/// mgr.run('grep', ['-i', 'main', 'test.dart']).then((result) {
/// stdout.write(result.stdout);
/// stderr.write(result.stderr);
/// });
/// ```
Future<ProcessResult> run(
List<Object> command, {
String? workingDirectory,
Expand Down
2 changes: 1 addition & 1 deletion packages/process/pubspec.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: process
description: A pluggable, mockable process invocation abstraction for Dart.
repository: https://github.com/flutter/packages/tree/main/packages/process
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+process%22
version: 5.0.2
version: 5.0.3

environment:
sdk: ^3.3.0
Expand Down
3 changes: 2 additions & 1 deletion packages/rfw/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
## NEXT
## 1.0.30

* Adds `missing_code_block_language_in_doc_comment` lint.
* Updates minimum supported SDK version to Flutter 3.19/Dart 3.3.

## 1.0.29
Expand Down
42 changes: 27 additions & 15 deletions packages/rfw/lib/src/dart/binary.dart
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,9 @@ Uint8List encodeLibraryBlob(RemoteWidgetLibrary value) {
///
/// For example, the string "Hello" would be encoded as:
///
/// 05 00 00 00 00 00 00 00 48 65 6C 6C 6F
/// ```none
/// 05 00 00 00 00 00 00 00 48 65 6C 6C 6F
/// ```
///
/// * Lists are encoded as an integer length, followed by that many values
/// back to back. When lists are of specific types (e.g. lists of imports),
Expand All @@ -124,15 +126,19 @@ Uint8List encodeLibraryBlob(RemoteWidgetLibrary value) {
/// followed by the value (tagged lists). For example, a list of integers with
/// the values 1 and 2 in that order would be encoded as:
///
/// 02 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00
/// 02 00 00 00 00 00 00 00
/// ```none
/// 02 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00
/// 02 00 00 00 00 00 00 00
/// ```
///
/// A list of arbitrary values that happens to contain one string "Hello"
/// would be encoded as follows; 0x04 is the tag for "String" (the full list
/// of tags is described below):
///
/// 01 00 00 00 00 00 00 00 04 05 00 00 00 00 00 00
/// 00 48 65 6C 6C 6F
/// ```none
/// 01 00 00 00 00 00 00 00 04 05 00 00 00 00 00 00
/// 00 48 65 6C 6C 6F
/// ```
///
/// A list of length zero is eight zero bytes with no additional payload.
///
Expand All @@ -147,8 +153,10 @@ Uint8List encodeLibraryBlob(RemoteWidgetLibrary value) {
/// strings, so they are untagged) is encoded as follows (0x02 is the tag for
/// integers):
///
/// 01 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00
/// 61 02 0F 00 00 00 00 00 00 00
/// ```none
/// 01 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00
/// 61 02 0F 00 00 00 00 00 00 00
/// ```
///
/// Objects are encoded as follows:
///
Expand All @@ -159,8 +167,10 @@ Uint8List encodeLibraryBlob(RemoteWidgetLibrary value) {
/// one of the subparts of the imported library name. For example, `import
/// a.b` is encoded as:
///
/// 02 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00
/// 61 01 00 00 00 00 00 00 00 62
/// ```none
/// 02 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00
/// 61 01 00 00 00 00 00 00 00 62
/// ```
///
/// * Widget declarations are encoded as a string giving the declaration name,
/// an untagged map for the initial state, and finally the value that
Expand Down Expand Up @@ -220,7 +230,7 @@ Uint8List encodeLibraryBlob(RemoteWidgetLibrary value) {
///
/// For example, this switch:
///
/// ```
/// ```none
/// switch (args.a) {
/// 0: 'z',
/// 1: 'o',
Expand All @@ -230,11 +240,13 @@ Uint8List encodeLibraryBlob(RemoteWidgetLibrary value) {
///
/// ...is encoded as follows (including the tag for the switch itself):
///
/// 0F 0A 01 00 00 00 00 00 00 00 61 03 00 00 00 00
/// 00 00 00 02 00 00 00 00 00 00 00 00 04 01 00 00
/// 00 00 00 00 00 7A 02 01 00 00 00 00 00 00 00 04
/// 01 00 00 00 00 00 00 00 6F 10 04 01 00 00 00 00
/// 00 00 00 64
/// ```none
/// 0F 0A 01 00 00 00 00 00 00 00 61 03 00 00 00 00
/// 00 00 00 02 00 00 00 00 00 00 00 00 04 01 00 00
/// 00 00 00 00 00 7A 02 01 00 00 00 00 00 00 00 04
/// 01 00 00 00 00 00 00 00 6F 10 04 01 00 00 00 00
/// 00 00 00 64
/// ```
///
/// * Event handlers have the tag 0x0E, and are encoded as a string
/// ([EventHandler.eventName]) and an untagged map
Expand Down
Loading

0 comments on commit 79f8b0b

Please sign in to comment.