Add `missing_code_block_language_in_doc_comment` lint to flutter/engine. (#51944)
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.
Lint Proposal: https://github.com/dart-lang/linter/issues/4904
## 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 [Flutter Style Guide] and the [C++,
Objective-C, Java style guides].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [X] I added new tests to check the change I am making or feature I am
adding, or the PR is [test-exempt]. See [testing the engine] for
instructions on writing and running engine tests.
- [X] I updated/added relevant documentation (doc comments with `///`).
- [X] I signed the [CLA].
- [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/flutter/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[test-exempt]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[C++, Objective-C, Java style guides]:
https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
[testing the engine]:
https://github.com/flutter/flutter/wiki/Testing-the-engine
[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
diff --git a/analysis_options.yaml b/analysis_options.yaml
index d7c1e8b..1defc1b 100644
--- a/analysis_options.yaml
+++ b/analysis_options.yaml
@@ -110,6 +110,7 @@
# - 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 # DIFFERENT FROM FLUTTER/FLUTTER (too many false positives)
- no_adjacent_strings_in_list
- no_default_cases
diff --git a/lib/web_ui/lib/src/engine/color_filter.dart b/lib/web_ui/lib/src/engine/color_filter.dart
index 850df88..83a7ca2 100644
--- a/lib/web_ui/lib/src/engine/color_filter.dart
+++ b/lib/web_ui/lib/src/engine/color_filter.dart
@@ -49,7 +49,7 @@
/// The matrix is in row-major order and the translation column is specified
/// in unnormalized, 0...255, space. For example, the identity matrix is:
///
- /// ```
+ /// ```dart
/// const ColorMatrix identity = ColorFilter.matrix(<double>[
/// 1, 0, 0, 0, 0,
/// 0, 1, 0, 0, 0,
@@ -62,7 +62,7 @@
///
/// An inversion color matrix:
///
- /// ```
+ /// ```dart
/// const ColorFilter invert = ColorFilter.matrix(<double>[
/// -1, 0, 0, 0, 255,
/// 0, -1, 0, 0, 255,
@@ -73,7 +73,7 @@
///
/// A sepia-toned color matrix (values based on the [Filter Effects Spec](https://www.w3.org/TR/filter-effects-1/#sepiaEquivalent)):
///
- /// ```
+ /// ```dart
/// const ColorFilter sepia = ColorFilter.matrix(<double>[
/// 0.393, 0.769, 0.189, 0, 0,
/// 0.349, 0.686, 0.168, 0, 0,
@@ -84,7 +84,7 @@
///
/// A greyscale color filter (values based on the [Filter Effects Spec](https://www.w3.org/TR/filter-effects-1/#grayscaleEquivalent)):
///
- /// ```
+ /// ```dart
/// const ColorFilter greyscale = ColorFilter.matrix(<double>[
/// 0.2126, 0.7152, 0.0722, 0, 0,
/// 0.2126, 0.7152, 0.0722, 0, 0,
diff --git a/lib/web_ui/lib/src/engine/configuration.dart b/lib/web_ui/lib/src/engine/configuration.dart
index 5591598..4428142 100644
--- a/lib/web_ui/lib/src/engine/configuration.dart
+++ b/lib/web_ui/lib/src/engine/configuration.dart
@@ -231,7 +231,7 @@
///
/// Example:
///
- /// ```
+ /// ```bash
/// flutter run \
/// -d chrome \
/// --web-renderer=canvaskit \
@@ -279,7 +279,7 @@
///
/// Example:
///
- /// ```
+ /// ```bash
/// flutter run -d chrome --profile --dart-define=FLUTTER_WEB_DEBUG_SHOW_SEMANTICS=true
/// ```
bool get debugShowSemanticsNodes =>
diff --git a/lib/web_ui/lib/src/engine/profiler.dart b/lib/web_ui/lib/src/engine/profiler.dart
index d5ef8b3..5a5c137 100644
--- a/lib/web_ui/lib/src/engine/profiler.dart
+++ b/lib/web_ui/lib/src/engine/profiler.dart
@@ -33,9 +33,9 @@
///
/// Example:
///
-/// ```
+/// ```dart
/// final result = timeAction('expensive_operation', () {
-/// ... expensive work ...
+/// // ... expensive work ...
/// return someValue;
/// });
/// ```
diff --git a/lib/web_ui/lib/src/engine/text/line_breaker.dart b/lib/web_ui/lib/src/engine/text/line_breaker.dart
index 98b02aa..5e24a28 100644
--- a/lib/web_ui/lib/src/engine/text/line_breaker.dart
+++ b/lib/web_ui/lib/src/engine/text/line_breaker.dart
@@ -210,7 +210,7 @@
/// way from 0 to the string length. For example, here are the indices for the
/// string "foo bar":
///
-/// ```
+/// ```none
/// f o o b a r
/// ^ ^ ^ ^ ^ ^ ^ ^
/// 0 1 2 3 4 5 6 7
diff --git a/lib/web_ui/lib/src/engine/window.dart b/lib/web_ui/lib/src/engine/window.dart
index c82edb2..e664d76 100644
--- a/lib/web_ui/lib/src/engine/window.dart
+++ b/lib/web_ui/lib/src/engine/window.dart
@@ -181,7 +181,7 @@
/// so it can push/shrink inside its `hostElement`. That way, a Flutter app
/// can change the layout of the container page.
///
- /// ```
+ /// ```none
/// <p>Some HTML content...</p>
/// +--- (div) hostElement ------------------------------------+
/// | +--- rootElement ---------------------+ |
diff --git a/lib/web_ui/test/canvaskit/fragment_program_test.dart b/lib/web_ui/test/canvaskit/fragment_program_test.dart
index 6395ae0..b0899e1 100644
--- a/lib/web_ui/test/canvaskit/fragment_program_test.dart
+++ b/lib/web_ui/test/canvaskit/fragment_program_test.dart
@@ -184,8 +184,8 @@
}
''';
-/// Geenrated by impellerc from
-/// ```
+/// Generated by impellerc from
+/// ```cpp
/// #include <flutter/runtime_effect.glsl>
/// uniform vec2 uSize;
/// uniform float[10] uFloats;
diff --git a/testing/scenario_app/bin/utils/options.dart b/testing/scenario_app/bin/utils/options.dart
index 91b9e44..852460d 100644
--- a/testing/scenario_app/bin/utils/options.dart
+++ b/testing/scenario_app/bin/utils/options.dart
@@ -65,7 +65,7 @@
/// This is a shortcut that can be used to determine if the usage information
/// before parsing the remaining command line arguments. For example:
///
- /// ```
+ /// ```dart
/// void main(List<String> args) {
/// if (Options.showUsage(args)) {
/// stdout.writeln(Options.usage);
@@ -88,7 +88,7 @@
/// be enabled before parsing the remaining command line arguments. For
/// example:
///
- /// ```
+ /// ```dart
/// void main(List<String> args) {
/// final bool verbose = Options.showVerbose(args);
/// // ...
diff --git a/testing/skia_gold_client/lib/skia_gold_client.dart b/testing/skia_gold_client/lib/skia_gold_client.dart
index 9d14d01..c7866c0 100644
--- a/testing/skia_gold_client/lib/skia_gold_client.dart
+++ b/testing/skia_gold_client/lib/skia_gold_client.dart
@@ -297,7 +297,7 @@
/// [pixelColorDelta] defines maximum acceptable difference in RGB channels of
/// each pixel, such that:
///
- /// ```
+ /// ```dart
/// bool isSame(Color image, Color golden, int pixelDeltaThreshold) {
/// return abs(image.r - golden.r)
/// + abs(image.g - golden.g)
diff --git a/third_party/web_unicode/tool/unicode_sync_script.dart b/third_party/web_unicode/tool/unicode_sync_script.dart
index 3f3573d..04c79bb 100644
--- a/third_party/web_unicode/tool/unicode_sync_script.dart
+++ b/third_party/web_unicode/tool/unicode_sync_script.dart
@@ -369,7 +369,7 @@
/// Example:
///
-/// ```
+/// ```none
/// 0x01C4..0x0293; ALetter
/// 0x0294..0x0294; ALetter
/// 0x0295..0x02AF; ALetter
@@ -377,7 +377,7 @@
///
/// will get combined into:
///
-/// ```
+/// ```none
/// 0x01C4..0x02AF; ALetter
/// ```
List<UnicodeRange> combineAdjacentRanges(
