Skip to content

Commit 4b4287b

Browse files
authored
Make it an error to break macros in docs (and fix existing broken macros) (#62071)
1 parent cac22cd commit 4b4287b

13 files changed

Lines changed: 104 additions & 136 deletions

File tree

‎dartdoc_options.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,10 @@ dartdoc:
1212
dartpad:
1313
command: ["dev/snippets/lib/main.dart", "--type=sample", "--dartpad"]
1414
description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."
15+
errors:
16+
- tool-error # enabled by default
17+
- duplicate-file # enabled by default
18+
- invalid-parameter # enabled by default
19+
- unresolved-export # enabled by default
20+
- unknown-macro # a {@macro foo} reference cannot be resolved
21+
- invalid-parameter # an invalid parameter is passed to a {@foo x y} directive

‎packages/flutter/lib/src/material/button.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ class RawMaterialButton extends StatefulWidget {
119119
/// * [MaterialState.disabled].
120120
///
121121
/// If this property is null, [MaterialStateMouseCursor.clickable] will be used.
122-
/// {@endtemplate flutter.material.button.mouseCursor}
122+
/// {@endtemplate}
123123
final MouseCursor mouseCursor;
124124

125125
/// Defines the default text style, with [Material.textStyle], for the

‎packages/flutter/lib/src/material/color_scheme.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ class ColorScheme with Diagnosticable {
245245

246246
/// Linearly interpolate between two [ColorScheme] objects.
247247
///
248-
/// {@macro flutter.material.themeData.lerp}
248+
/// {@macro dart.ui.shadow.lerp}
249249
static ColorScheme lerp(ColorScheme a, ColorScheme b, double t) {
250250
return ColorScheme(
251251
primary: Color.lerp(a.primary, b.primary, t),

‎packages/flutter/lib/src/material/icon_button.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,7 @@ class IconButton extends StatelessWidget {
278278
/// If this is set to null, the button will be disabled.
279279
final VoidCallback onPressed;
280280

281-
/// {@macro flutter.material.inkwell.mousecursor}
281+
/// {@macro flutter.material.button.mouseCursor}
282282
///
283283
/// Defaults to [SystemMouseCursors.click].
284284
final MouseCursor mouseCursor;

‎packages/flutter/lib/src/material/scaffold.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ class ScaffoldPrelayoutGeometry {
126126
/// The minimum padding to inset the [FloatingActionButton] by for it
127127
/// to remain visible.
128128
///
129-
/// This value is the result of calling [MediaQuery.padding] in the
129+
/// This value is the result of calling [MediaQueryData.padding] in the
130130
/// [Scaffold]'s [BuildContext],
131131
/// and is useful for insetting the [FloatingActionButton] to avoid features like
132132
/// the system status bar or the keyboard.

‎packages/flutter/lib/src/material/slider_theme.dart‎

Lines changed: 80 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -15,146 +15,53 @@ import 'colors.dart';
1515
import 'theme.dart';
1616
import 'theme_data.dart';
1717

18+
/// Applies a slider theme to descendant [Slider] widgets.
19+
///
20+
/// A slider theme describes the colors and shape choices of the slider
21+
/// components.
22+
///
23+
/// Descendant widgets obtain the current theme's [SliderThemeData] object using
24+
/// [SliderTheme.of]. When a widget uses [SliderTheme.of], it is automatically
25+
/// rebuilt if the theme later changes.
26+
///
27+
/// The slider is as big as the largest of
28+
/// the [SliderComponentShape.getPreferredSize] of the thumb shape,
29+
/// the [SliderComponentShape.getPreferredSize] of the overlay shape,
30+
/// and the [SliderTickMarkShape.getPreferredSize] of the tick mark shape
31+
///
32+
/// See also:
33+
///
34+
/// * [SliderThemeData], which describes the actual configuration of a slider
35+
/// theme.
1836
/// {@template flutter.material.slider.seeAlso.sliderComponentShape}
1937
/// * [SliderComponentShape], which can be used to create custom shapes for
2038
/// the [Slider]'s thumb, overlay, and value indicator and the
2139
/// [RangeSlider]'s overlay.
2240
/// {@endtemplate}
23-
///
2441
/// {@template flutter.material.slider.seeAlso.sliderTrackShape}
2542
/// * [SliderTrackShape], which can be used to create custom shapes for the
2643
/// [Slider]'s track.
2744
/// {@endtemplate}
28-
///
2945
/// {@template flutter.material.slider.seeAlso.sliderTickMarkShape}
3046
/// * [SliderTickMarkShape], which can be used to create custom shapes for the
3147
/// [Slider]'s tick marks.
3248
/// {@endtemplate}
33-
///
3449
/// {@template flutter.material.slider.seeAlso.rangeSliderThumbShape}
3550
/// * [RangeSliderThumbShape], which can be used to create custom shapes for
3651
/// the [RangeSlider]'s thumb.
3752
/// {@endtemplate}
38-
///
3953
/// {@template flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
4054
/// * [RangeSliderValueIndicatorShape], which can be used to create custom
4155
/// shapes for the [RangeSlider]'s value indicator.
4256
/// {@endtemplate}
43-
///
4457
/// {@template flutter.material.slider.seeAlso.rangeSliderTrackShape}
4558
/// * [RangeSliderTrackShape], which can be used to create custom shapes for
4659
/// the [RangeSlider]'s track.
4760
/// {@endtemplate}
48-
///
4961
/// {@template flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
5062
/// * [RangeSliderTickMarkShape], which can be used to create custom shapes for
5163
/// the [RangeSlider]'s tick marks.
5264
/// {@endtemplate}
53-
///
54-
/// {@template flutter.material.slider.seeAlso.roundSliderThumbShape}
55-
/// * [RoundSliderThumbShape], which is the default [Slider]'s thumb shape that
56-
/// paints a solid circle.
57-
/// {@endtemplate}
58-
///
59-
/// {@template flutter.material.slider.seeAlso.roundSliderOverlayShape}
60-
/// * [RoundSliderOverlayShape], which is the default [Slider] and
61-
/// [RangeSlider]'s overlay shape that paints a transparent circle.
62-
/// {@endtemplate}
63-
///
64-
/// {@template flutter.material.slider.seeAlso.paddleSliderValueIndicatorShape}
65-
/// * [PaddleSliderValueIndicatorShape], which is the default [Slider]'s value
66-
/// indicator shape that paints a custom path with text in it.
67-
/// {@endtemplate}
68-
///
69-
/// {@template flutter.material.slider.seeAlso.roundSliderTickMarkShape}
70-
/// * [RoundSliderTickMarkShape], which is the default [Slider]'s tick mark
71-
/// shape that paints a solid circle.
72-
/// {@endtemplate}
73-
///
74-
/// {@template flutter.material.slider.seeAlso.roundedRectSliderTrackShape}
75-
/// * [RoundedRectSliderTrackShape] for the default [Slider]'s track shape that
76-
/// paints a stadium-like track.
77-
/// {@endtemplate}
78-
///
79-
/// {@template flutter.material.slider.seeAlso.roundRangeSliderThumbShape}
80-
/// * [RoundRangeSliderThumbShape] for the default [RangeSlider]'s thumb shape
81-
/// that paints a solid circle.
82-
/// {@endtemplate}
83-
///
84-
/// {@template flutter.material.slider.seeAlso.paddleRangeSliderValueIndicatorShape}
85-
/// * [PaddleRangeSliderValueIndicatorShape] for the default [RangeSlider]'s
86-
/// value indicator shape that paints a custom path with text in it.
87-
/// {@endtemplate}
88-
///
89-
/// {@template flutter.material.slider.seeAlso.roundRangeSliderTickMarkShape}
90-
/// * [RoundRangeSliderTickMarkShape] for the default [RangeSlider]'s tick mark
91-
/// shape that paints a solid circle.
92-
/// {@endtemplate}
93-
///
94-
/// {@template flutter.material.slider.seeAlso.roundedRectRangeSliderTrackShape}
95-
/// * [RoundedRectRangeSliderTrackShape] for the default [RangeSlider]'s track
96-
/// shape that paints a stadium-like track.
97-
/// {@endtemplate}
98-
///
99-
/// {@template flutter.material.slider.trackSegment}
100-
/// The track segment between the start of the slider and the thumb is the
101-
/// active track segment. The track segment between the thumb and the end of the
102-
/// slider is the inactive track segment. In [TextDirection.ltr], the start of
103-
/// the slider is on the left, and in [TextDirection.rtl], the start of the
104-
/// slider is on the right.
105-
/// {@endtemplate}
106-
///
107-
/// {@template flutter.material.rangeSlider.trackSegment}
108-
/// The track segment between the two thumbs is the active track segment. The
109-
/// track segments between the thumb and each end of the slider are the inactive
110-
/// track segments. In [TextDirection.ltr], the start of the slider is on the
111-
/// left, and in [TextDirection.rtl], the start of the slider is on the right.
112-
/// {@endtemplate}
113-
///
114-
/// This is a temporary flag for migrating the slider from v1 to v2. To avoid
115-
/// unexpected breaking changes, this value should be set to true. Setting
116-
/// this to false is considered deprecated.
117-
/// {@endtemplate}
118-
///
119-
/// {@template flutter.material.slider.shape.textScaleFactor}
120-
/// Can be used to determine whether the component should
121-
/// paint larger or smaller, depending on whether [textScaleFactor] is greater
122-
/// than 1 for larger, and between 0 and 1 for smaller. It usually comes from
123-
/// [MediaQueryData.textScaleFactor].
124-
/// {@endtemplate}
125-
///
126-
/// {@template flutter.material.rangeSlider.shape.sizeWithOverflow}
127-
/// Can be used to determine the bounds the drawing of the
128-
/// components that are outside of the regular slider bounds. It's the size of
129-
/// the box, whose center is aligned with the slider's bounds, that the value
130-
/// indicators must be drawn within. Typically, it is bigger than the slider.
131-
/// {@endtemplate}
132-
133-
/// Applies a slider theme to descendant [Slider] widgets.
134-
///
135-
/// A slider theme describes the colors and shape choices of the slider
136-
/// components.
137-
///
138-
/// Descendant widgets obtain the current theme's [SliderThemeData] object using
139-
/// [SliderTheme.of]. When a widget uses [SliderTheme.of], it is automatically
140-
/// rebuilt if the theme later changes.
141-
///
142-
/// The slider is as big as the largest of
143-
/// the [SliderComponentShape.getPreferredSize] of the thumb shape,
144-
/// the [SliderComponentShape.getPreferredSize] of the overlay shape,
145-
/// and the [SliderTickMarkShape.getPreferredSize] of the tick mark shape
146-
///
147-
/// See also:
148-
///
149-
/// * [SliderThemeData], which describes the actual configuration of a slider
150-
/// theme.
151-
/// {@macro flutter.material.slider.seeAlso.sliderComponentShape}
152-
/// {@macro flutter.material.slider.seeAlso.sliderTrackShape}
153-
/// {@macro flutter.material.slider.seeAlso.sliderTickMarkShape}
154-
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
155-
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
156-
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
157-
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
15865
class SliderTheme extends InheritedTheme {
15966
/// Applies the given theme [data] to [child].
16067
///
@@ -961,9 +868,18 @@ class SliderThemeData with Diagnosticable {
961868
///
962869
/// See also:
963870
///
964-
/// {@macro flutter.material.slider.seeAlso.roundSliderThumbShape}
965-
/// {@macro flutter.material.slider.seeAlso.roundSliderOverlayShape}
966-
/// {@macro flutter.material.slider.seeAlso.paddleSliderValueIndicatorShape}
871+
/// {@template flutter.material.slider.seeAlso.roundSliderThumbShape}
872+
/// * [RoundSliderThumbShape], which is the default [Slider]'s thumb shape that
873+
/// paints a solid circle.
874+
/// {@endtemplate}
875+
/// {@template flutter.material.slider.seeAlso.roundSliderOverlayShape}
876+
/// * [RoundSliderOverlayShape], which is the default [Slider] and
877+
/// [RangeSlider]'s overlay shape that paints a transparent circle.
878+
/// {@endtemplate}
879+
/// {@template flutter.material.slider.seeAlso.paddleSliderValueIndicatorShape}
880+
/// * [PaddleSliderValueIndicatorShape], which is the default [Slider]'s value
881+
/// indicator shape that paints a custom path with text in it.
882+
/// {@endtemplate}
967883
abstract class SliderComponentShape {
968884
/// This abstract const constructor enables subclasses to provide
969885
/// const constructors so that they can be used in const expressions.
@@ -1000,9 +916,19 @@ abstract class SliderComponentShape {
1000916
///
1001917
/// [value] is the current parametric value (from 0.0 to 1.0) of the slider.
1002918
///
1003-
/// {@macro flutter.material.slider.shape.textScaleFactor}
1004-
///
1005-
/// {@macro flutter.material.slider.shape.sizeWithOverflow}
919+
/// {@template flutter.material.slider.shape.textScaleFactor}
920+
/// Can be used to determine whether the component should
921+
/// paint larger or smaller, depending on whether [textScaleFactor] is greater
922+
/// than 1 for larger, and between 0 and 1 for smaller. It usually comes from
923+
/// [MediaQueryData.textScaleFactor].
924+
/// {@endtemplate}
925+
///
926+
/// {@template flutter.material.slider.shape.sizeWithOverflow}
927+
/// Can be used to determine the bounds the drawing of the
928+
/// components that are outside of the regular slider bounds. It's the size of
929+
/// the box, whose center is aligned with the slider's bounds, that the value
930+
/// indicators must be drawn within. Typically, it is bigger than the slider.
931+
/// {@endtemplate}
1006932
void paint(
1007933
PaintingContext context,
1008934
Offset center, {
@@ -1044,7 +970,10 @@ abstract class SliderComponentShape {
1044970
///
1045971
/// See also:
1046972
///
1047-
/// {@macro flutter.material.slider.seeAlso.roundSliderTickMarkShape}
973+
/// {@template flutter.material.slider.seeAlso.roundSliderTickMarkShape}
974+
/// * [RoundSliderTickMarkShape], which is the default [Slider]'s tick mark
975+
/// shape that paints a solid circle.
976+
/// {@endtemplate}
1048977
/// {@macro flutter.material.slider.seeAlso.sliderTrackShape}
1049978
/// {@macro flutter.material.slider.seeAlso.sliderComponentShape}
1050979
abstract class SliderTickMarkShape {
@@ -1116,7 +1045,8 @@ abstract class SliderTickMarkShape {
11161045
///
11171046
/// See also:
11181047
///
1119-
/// {@macro flutter.material.slider.seeAlso.roundedRectSliderTrackShape}
1048+
/// * [RoundedRectSliderTrackShape] for the default [Slider]'s track shape that
1049+
/// paints a stadium-like track.
11201050
/// {@macro flutter.material.slider.seeAlso.sliderTickMarkShape}
11211051
/// {@macro flutter.material.slider.seeAlso.sliderComponentShape}
11221052
abstract class SliderTrackShape {
@@ -1172,7 +1102,14 @@ abstract class SliderTrackShape {
11721102
///
11731103
/// The [textDirection] argument can be used to determine how the track segments are
11741104
/// painted depending on whether they are active or not.
1175-
/// {@macro flutter.material.slider.trackSegment}
1105+
///
1106+
/// {@template flutter.material.slider.trackSegment}
1107+
/// The track segment between the start of the slider and the thumb is the
1108+
/// active track segment. The track segment between the thumb and the end of the
1109+
/// slider is the inactive track segment. In [TextDirection.ltr], the start of
1110+
/// the slider is on the left, and in [TextDirection.rtl], the start of the
1111+
/// slider is on the right.
1112+
/// {@endtemplate}
11761113
void paint(
11771114
PaintingContext context,
11781115
Offset offset, {
@@ -1190,7 +1127,10 @@ abstract class SliderTrackShape {
11901127
///
11911128
/// See also:
11921129
///
1193-
/// {@macro flutter.material.slider.seeAlso.roundRangeSliderThumbShape}
1130+
/// {@template flutter.material.slider.seeAlso.roundRangeSliderThumbShape}
1131+
/// * [RoundRangeSliderThumbShape] for the default [RangeSlider]'s thumb shape
1132+
/// that paints a solid circle.
1133+
/// {@endtemplate}
11941134
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
11951135
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
11961136
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
@@ -1253,7 +1193,10 @@ abstract class RangeSliderThumbShape {
12531193
///
12541194
/// See also:
12551195
///
1256-
/// {@macro flutter.material.slider.seeAlso.paddleRangeSliderValueIndicatorShape}
1196+
/// {@template flutter.material.slider.seeAlso.paddleRangeSliderValueIndicatorShape}
1197+
/// * [PaddleRangeSliderValueIndicatorShape] for the default [RangeSlider]'s
1198+
/// value indicator shape that paints a custom path with text in it.
1199+
/// {@endtemplate}
12571200
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
12581201
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
12591202
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
@@ -1352,7 +1295,10 @@ abstract class RangeSliderValueIndicatorShape {
13521295
///
13531296
/// See also:
13541297
///
1355-
/// {@macro flutter.material.slider.seeAlso.roundRangeSliderTickMarkShape}
1298+
/// {@template flutter.material.slider.seeAlso.roundRangeSliderTickMarkShape}
1299+
/// * [RoundRangeSliderTickMarkShape] for the default [RangeSlider]'s tick mark
1300+
/// shape that paints a solid circle.
1301+
/// {@endtemplate}
13561302
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
13571303
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
13581304
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
@@ -1390,7 +1336,13 @@ abstract class RangeSliderTickMarkShape {
13901336
///
13911337
/// The [textDirection] argument can be used to determine how the tick marks are painted
13921338
/// depending on whether they are on an active track segment or not.
1393-
/// {@macro flutter.material.rangeSlider.trackSegment}
1339+
///
1340+
/// {@template flutter.material.rangeSlider.trackSegment}
1341+
/// The track segment between the two thumbs is the active track segment. The
1342+
/// track segments between the thumb and each end of the slider are the inactive
1343+
/// track segments. In [TextDirection.ltr], the start of the slider is on the
1344+
/// left, and in [TextDirection.rtl], the start of the slider is on the right.
1345+
/// {@endtemplate}
13941346
void paint(
13951347
PaintingContext context,
13961348
Offset center, {
@@ -1415,7 +1367,10 @@ abstract class RangeSliderTickMarkShape {
14151367
///
14161368
/// See also:
14171369
///
1418-
/// {@macro flutter.material.slider.seeAlso.roundedRectRangeSliderTrackShape}
1370+
/// {@template flutter.material.slider.seeAlso.roundedRectRangeSliderTrackShape}
1371+
/// * [RoundedRectRangeSliderTrackShape] for the default [RangeSlider]'s track
1372+
/// shape that paints a stadium-like track.
1373+
/// {@endtemplate}
14191374
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
14201375
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
14211376
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}

‎packages/flutter/lib/src/material/text_theme.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -685,7 +685,7 @@ class TextTheme with Diagnosticable {
685685

686686
/// Linearly interpolate between two text themes.
687687
///
688-
/// {@macro flutter.material.themeData.lerp}
688+
/// {@macro dart.ui.shadow.lerp}
689689
static TextTheme lerp(TextTheme a, TextTheme b, double t) {
690690
assert(t != null);
691691
return TextTheme(

‎packages/flutter/lib/src/rendering/editable.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -330,7 +330,7 @@ class RenderEditable extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
330330
markNeedsTextLayout();
331331
}
332332

333-
/// {@macro flutter.widgets.text.DefaultTextStyle.textWidthBasis}
333+
/// {@macro flutter.painting.textPainter.textWidthBasis}
334334
TextWidthBasis get textWidthBasis => _textPainter.textWidthBasis;
335335
set textWidthBasis(TextWidthBasis value) {
336336
assert(value != null);

‎packages/flutter/lib/src/rendering/paragraph.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -269,7 +269,7 @@ class RenderParagraph extends RenderBox
269269
markNeedsLayout();
270270
}
271271

272-
/// {@macro flutter.widgets.basic.TextWidthBasis}
272+
/// {@macro flutter.painting.textPainter.textWidthBasis}
273273
TextWidthBasis get textWidthBasis => _textPainter.textWidthBasis;
274274
set textWidthBasis(TextWidthBasis value) {
275275
assert(value != null);

‎packages/flutter/lib/src/services/raw_keyboard_windows.dart‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,11 @@ class RawKeyEventDataWindows extends RawKeyEventData {
210210
/// This mask is used to check the [modifiers] field to test whether one of the
211211
/// SHIFT modifier keys is pressed.
212212
///
213-
/// {@macro flutter.services.rawKeyEventDataWindows.modifiers}
213+
/// {@template flutter.services.rawKeyEventDataWindows.modifiers}
214+
/// Use this value if you need to decode the [modifiers] field yourself, but
215+
/// it's much easier to use [isModifierPressed] if you just want to know if
216+
/// a modifier is pressed.
217+
/// {@endtemplate}
214218
static const int modifierShift = 1 << 0;
215219

216220
/// This mask is used to check the [modifiers] field to test whether the left

0 commit comments

Comments
 (0)