firka/flutter
firka/flutter
5
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Make it an error to break macros in docs (and fix existing broken macros) (#62071)

Browse Source
This commit is contained in:
Michael Goderbauer 2020-07-23 08:29:46 -07:00 committed by GitHub
parent cac22cdb08
commit 4b4287ba78
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 114 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
dartdoc_options.yaml
View File

@ -12,3 +12,10 @@ dartdoc:
dartpad:
command: ["dev/snippets/lib/main.dart", "--type=sample", "--dartpad"]
description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad."
errors:
- tool-error # enabled by default
- duplicate-file # enabled by default
- invalid-parameter # enabled by default
- unresolved-export # enabled by default
- unknown-macro # a {@macro foo} reference cannot be resolved
- invalid-parameter # an invalid parameter is passed to a {@foo x y} directive

2
packages/flutter/lib/src/material/button.dart
View File

@ -119,7 +119,7 @@ class RawMaterialButton extends StatefulWidget {
/// * [MaterialState.disabled].
///
/// If this property is null, [MaterialStateMouseCursor.clickable] will be used.
/// {@endtemplate flutter.material.button.mouseCursor}
/// {@endtemplate}
final MouseCursor mouseCursor;
/// Defines the default text style, with [Material.textStyle], for the

2
packages/flutter/lib/src/material/color_scheme.dart
View File

@ -245,7 +245,7 @@ class ColorScheme with Diagnosticable {
/// Linearly interpolate between two [ColorScheme] objects.
///
/// {@macro flutter.material.themeData.lerp}
/// {@macro dart.ui.shadow.lerp}
static ColorScheme lerp(ColorScheme a, ColorScheme b, double t) {
return ColorScheme(
primary: Color.lerp(a.primary, b.primary, t),

2
packages/flutter/lib/src/material/icon_button.dart
View File

@ -278,7 +278,7 @@ class IconButton extends StatelessWidget {
/// If this is set to null, the button will be disabled.
final VoidCallback onPressed;
/// {@macro flutter.material.inkwell.mousecursor}
/// {@macro flutter.material.button.mouseCursor}
///
/// Defaults to [SystemMouseCursors.click].
final MouseCursor mouseCursor;

2
packages/flutter/lib/src/material/scaffold.dart
View File

@ -126,7 +126,7 @@ class ScaffoldPrelayoutGeometry {
/// The minimum padding to inset the [FloatingActionButton] by for it
/// to remain visible.
///
/// This value is the result of calling [MediaQuery.padding] in the
/// This value is the result of calling [MediaQueryData.padding] in the
/// [Scaffold]'s [BuildContext],
/// and is useful for insetting the [FloatingActionButton] to avoid features like
/// the system status bar or the keyboard.

225
packages/flutter/lib/src/material/slider_theme.dart
View File

@ -15,121 +15,6 @@ import 'colors.dart';
import 'theme.dart';
import 'theme_data.dart';
/// {@template flutter.material.slider.seeAlso.sliderComponentShape}
/// * [SliderComponentShape], which can be used to create custom shapes for
/// the [Slider]'s thumb, overlay, and value indicator and the
/// [RangeSlider]'s overlay.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.sliderTrackShape}
/// * [SliderTrackShape], which can be used to create custom shapes for the
/// [Slider]'s track.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.sliderTickMarkShape}
/// * [SliderTickMarkShape], which can be used to create custom shapes for the
/// [Slider]'s tick marks.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.rangeSliderThumbShape}
/// * [RangeSliderThumbShape], which can be used to create custom shapes for
/// the [RangeSlider]'s thumb.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
/// * [RangeSliderValueIndicatorShape], which can be used to create custom
/// shapes for the [RangeSlider]'s value indicator.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.rangeSliderTrackShape}
/// * [RangeSliderTrackShape], which can be used to create custom shapes for
/// the [RangeSlider]'s track.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
/// * [RangeSliderTickMarkShape], which can be used to create custom shapes for
/// the [RangeSlider]'s tick marks.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.roundSliderThumbShape}
/// * [RoundSliderThumbShape], which is the default [Slider]'s thumb shape that
/// paints a solid circle.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.roundSliderOverlayShape}
/// * [RoundSliderOverlayShape], which is the default [Slider] and
/// [RangeSlider]'s overlay shape that paints a transparent circle.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.paddleSliderValueIndicatorShape}
/// * [PaddleSliderValueIndicatorShape], which is the default [Slider]'s value
/// indicator shape that paints a custom path with text in it.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.roundSliderTickMarkShape}
/// * [RoundSliderTickMarkShape], which is the default [Slider]'s tick mark
/// shape that paints a solid circle.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.roundedRectSliderTrackShape}
/// * [RoundedRectSliderTrackShape] for the default [Slider]'s track shape that
/// paints a stadium-like track.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.roundRangeSliderThumbShape}
/// * [RoundRangeSliderThumbShape] for the default [RangeSlider]'s thumb shape
/// that paints a solid circle.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.paddleRangeSliderValueIndicatorShape}
/// * [PaddleRangeSliderValueIndicatorShape] for the default [RangeSlider]'s
/// value indicator shape that paints a custom path with text in it.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.roundRangeSliderTickMarkShape}
/// * [RoundRangeSliderTickMarkShape] for the default [RangeSlider]'s tick mark
/// shape that paints a solid circle.
/// {@endtemplate}
///
/// {@template flutter.material.slider.seeAlso.roundedRectRangeSliderTrackShape}
/// * [RoundedRectRangeSliderTrackShape] for the default [RangeSlider]'s track
/// shape that paints a stadium-like track.
/// {@endtemplate}
///
/// {@template flutter.material.slider.trackSegment}
/// The track segment between the start of the slider and the thumb is the
/// active track segment. The track segment between the thumb and the end of the
/// slider is the inactive track segment. In [TextDirection.ltr], the start of
/// the slider is on the left, and in [TextDirection.rtl], the start of the
/// slider is on the right.
/// {@endtemplate}
///
/// {@template flutter.material.rangeSlider.trackSegment}
/// The track segment between the two thumbs is the active track segment. The
/// track segments between the thumb and each end of the slider are the inactive
/// track segments. In [TextDirection.ltr], the start of the slider is on the
/// left, and in [TextDirection.rtl], the start of the slider is on the right.
/// {@endtemplate}
///
/// This is a temporary flag for migrating the slider from v1 to v2. To avoid
/// unexpected breaking changes, this value should be set to true. Setting
/// this to false is considered deprecated.
/// {@endtemplate}
///
/// {@template flutter.material.slider.shape.textScaleFactor}
/// Can be used to determine whether the component should
/// paint larger or smaller, depending on whether [textScaleFactor] is greater
/// than 1 for larger, and between 0 and 1 for smaller. It usually comes from
/// [MediaQueryData.textScaleFactor].
/// {@endtemplate}
///
/// {@template flutter.material.rangeSlider.shape.sizeWithOverflow}
/// Can be used to determine the bounds the drawing of the
/// components that are outside of the regular slider bounds. It's the size of
/// the box, whose center is aligned with the slider's bounds, that the value
/// indicators must be drawn within. Typically, it is bigger than the slider.
/// {@endtemplate}
/// Applies a slider theme to descendant [Slider] widgets.
///
/// A slider theme describes the colors and shape choices of the slider
@ -148,13 +33,35 @@ import 'theme_data.dart';
///
/// * [SliderThemeData], which describes the actual configuration of a slider
/// theme.
/// {@macro flutter.material.slider.seeAlso.sliderComponentShape}
/// {@macro flutter.material.slider.seeAlso.sliderTrackShape}
/// {@macro flutter.material.slider.seeAlso.sliderTickMarkShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
/// {@template flutter.material.slider.seeAlso.sliderComponentShape}
/// * [SliderComponentShape], which can be used to create custom shapes for
/// the [Slider]'s thumb, overlay, and value indicator and the
/// [RangeSlider]'s overlay.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.sliderTrackShape}
/// * [SliderTrackShape], which can be used to create custom shapes for the
/// [Slider]'s track.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.sliderTickMarkShape}
/// * [SliderTickMarkShape], which can be used to create custom shapes for the
/// [Slider]'s tick marks.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.rangeSliderThumbShape}
/// * [RangeSliderThumbShape], which can be used to create custom shapes for
/// the [RangeSlider]'s thumb.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
/// * [RangeSliderValueIndicatorShape], which can be used to create custom
/// shapes for the [RangeSlider]'s value indicator.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.rangeSliderTrackShape}
/// * [RangeSliderTrackShape], which can be used to create custom shapes for
/// the [RangeSlider]'s track.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
/// * [RangeSliderTickMarkShape], which can be used to create custom shapes for
/// the [RangeSlider]'s tick marks.
/// {@endtemplate}
class SliderTheme extends InheritedTheme {
/// Applies the given theme [data] to [child].
///
@ -961,9 +868,18 @@ class SliderThemeData with Diagnosticable {
///
/// See also:
///
/// {@macro flutter.material.slider.seeAlso.roundSliderThumbShape}
/// {@macro flutter.material.slider.seeAlso.roundSliderOverlayShape}
/// {@macro flutter.material.slider.seeAlso.paddleSliderValueIndicatorShape}
/// {@template flutter.material.slider.seeAlso.roundSliderThumbShape}
/// * [RoundSliderThumbShape], which is the default [Slider]'s thumb shape that
/// paints a solid circle.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.roundSliderOverlayShape}
/// * [RoundSliderOverlayShape], which is the default [Slider] and
/// [RangeSlider]'s overlay shape that paints a transparent circle.
/// {@endtemplate}
/// {@template flutter.material.slider.seeAlso.paddleSliderValueIndicatorShape}
/// * [PaddleSliderValueIndicatorShape], which is the default [Slider]'s value
/// indicator shape that paints a custom path with text in it.
/// {@endtemplate}
abstract class SliderComponentShape {
/// This abstract const constructor enables subclasses to provide
/// const constructors so that they can be used in const expressions.
@ -1000,9 +916,19 @@ abstract class SliderComponentShape {
///
/// [value] is the current parametric value (from 0.0 to 1.0) of the slider.
///
/// {@macro flutter.material.slider.shape.textScaleFactor}
/// {@template flutter.material.slider.shape.textScaleFactor}
/// Can be used to determine whether the component should
/// paint larger or smaller, depending on whether [textScaleFactor] is greater
/// than 1 for larger, and between 0 and 1 for smaller. It usually comes from
/// [MediaQueryData.textScaleFactor].
/// {@endtemplate}
///
/// {@macro flutter.material.slider.shape.sizeWithOverflow}
/// {@template flutter.material.slider.shape.sizeWithOverflow}
/// Can be used to determine the bounds the drawing of the
/// components that are outside of the regular slider bounds. It's the size of
/// the box, whose center is aligned with the slider's bounds, that the value
/// indicators must be drawn within. Typically, it is bigger than the slider.
/// {@endtemplate}
void paint(
PaintingContext context,
Offset center, {
@ -1044,7 +970,10 @@ abstract class SliderComponentShape {
///
/// See also:
///
/// {@macro flutter.material.slider.seeAlso.roundSliderTickMarkShape}
/// {@template flutter.material.slider.seeAlso.roundSliderTickMarkShape}
/// * [RoundSliderTickMarkShape], which is the default [Slider]'s tick mark
/// shape that paints a solid circle.
/// {@endtemplate}
/// {@macro flutter.material.slider.seeAlso.sliderTrackShape}
/// {@macro flutter.material.slider.seeAlso.sliderComponentShape}
abstract class SliderTickMarkShape {
@ -1116,7 +1045,8 @@ abstract class SliderTickMarkShape {
///
/// See also:
///
/// {@macro flutter.material.slider.seeAlso.roundedRectSliderTrackShape}
/// * [RoundedRectSliderTrackShape] for the default [Slider]'s track shape that
/// paints a stadium-like track.
/// {@macro flutter.material.slider.seeAlso.sliderTickMarkShape}
/// {@macro flutter.material.slider.seeAlso.sliderComponentShape}
abstract class SliderTrackShape {
@ -1172,7 +1102,14 @@ abstract class SliderTrackShape {
///
/// The [textDirection] argument can be used to determine how the track segments are
/// painted depending on whether they are active or not.
/// {@macro flutter.material.slider.trackSegment}
///
/// {@template flutter.material.slider.trackSegment}
/// The track segment between the start of the slider and the thumb is the
/// active track segment. The track segment between the thumb and the end of the
/// slider is the inactive track segment. In [TextDirection.ltr], the start of
/// the slider is on the left, and in [TextDirection.rtl], the start of the
/// slider is on the right.
/// {@endtemplate}
void paint(
PaintingContext context,
Offset offset, {
@ -1190,7 +1127,10 @@ abstract class SliderTrackShape {
///
/// See also:
///
/// {@macro flutter.material.slider.seeAlso.roundRangeSliderThumbShape}
/// {@template flutter.material.slider.seeAlso.roundRangeSliderThumbShape}
/// * [RoundRangeSliderThumbShape] for the default [RangeSlider]'s thumb shape
/// that paints a solid circle.
/// {@endtemplate}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
@ -1253,7 +1193,10 @@ abstract class RangeSliderThumbShape {
///
/// See also:
///
/// {@macro flutter.material.slider.seeAlso.paddleRangeSliderValueIndicatorShape}
/// {@template flutter.material.slider.seeAlso.paddleRangeSliderValueIndicatorShape}
/// * [PaddleRangeSliderValueIndicatorShape] for the default [RangeSlider]'s
/// value indicator shape that paints a custom path with text in it.
/// {@endtemplate}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
@ -1352,7 +1295,10 @@ abstract class RangeSliderValueIndicatorShape {
///
/// See also:
///
/// {@macro flutter.material.slider.seeAlso.roundRangeSliderTickMarkShape}
/// {@template flutter.material.slider.seeAlso.roundRangeSliderTickMarkShape}
/// * [RoundRangeSliderTickMarkShape] for the default [RangeSlider]'s tick mark
/// shape that paints a solid circle.
/// {@endtemplate}
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTrackShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}
@ -1390,7 +1336,13 @@ abstract class RangeSliderTickMarkShape {
///
/// The [textDirection] argument can be used to determine how the tick marks are painted
/// depending on whether they are on an active track segment or not.
/// {@macro flutter.material.rangeSlider.trackSegment}
///
/// {@template flutter.material.rangeSlider.trackSegment}
/// The track segment between the two thumbs is the active track segment. The
/// track segments between the thumb and each end of the slider are the inactive
/// track segments. In [TextDirection.ltr], the start of the slider is on the
/// left, and in [TextDirection.rtl], the start of the slider is on the right.
/// {@endtemplate}
void paint(
PaintingContext context,
Offset center, {
@ -1415,7 +1367,10 @@ abstract class RangeSliderTickMarkShape {
///
/// See also:
///
/// {@macro flutter.material.slider.seeAlso.roundedRectRangeSliderTrackShape}
/// {@template flutter.material.slider.seeAlso.roundedRectRangeSliderTrackShape}
/// * [RoundedRectRangeSliderTrackShape] for the default [RangeSlider]'s track
/// shape that paints a stadium-like track.
/// {@endtemplate}
/// {@macro flutter.material.slider.seeAlso.rangeSliderTickMarkShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderThumbShape}
/// {@macro flutter.material.slider.seeAlso.rangeSliderValueIndicatorShape}

2
packages/flutter/lib/src/material/text_theme.dart
View File

@ -685,7 +685,7 @@ class TextTheme with Diagnosticable {
/// Linearly interpolate between two text themes.
///
/// {@macro flutter.material.themeData.lerp}
/// {@macro dart.ui.shadow.lerp}
static TextTheme lerp(TextTheme a, TextTheme b, double t) {
assert(t != null);
return TextTheme(

2
packages/flutter/lib/src/rendering/editable.dart
View File

@ -330,7 +330,7 @@ class RenderEditable extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
markNeedsTextLayout();
}
/// {@macro flutter.widgets.text.DefaultTextStyle.textWidthBasis}
/// {@macro flutter.painting.textPainter.textWidthBasis}
TextWidthBasis get textWidthBasis => _textPainter.textWidthBasis;
set textWidthBasis(TextWidthBasis value) {
assert(value != null);

2
packages/flutter/lib/src/rendering/paragraph.dart
View File

@ -269,7 +269,7 @@ class RenderParagraph extends RenderBox
markNeedsLayout();
}
/// {@macro flutter.widgets.basic.TextWidthBasis}
/// {@macro flutter.painting.textPainter.textWidthBasis}
TextWidthBasis get textWidthBasis => _textPainter.textWidthBasis;
set textWidthBasis(TextWidthBasis value) {
assert(value != null);

6
packages/flutter/lib/src/services/raw_keyboard_windows.dart
View File

@ -210,7 +210,11 @@ class RawKeyEventDataWindows extends RawKeyEventData {
/// This mask is used to check the [modifiers] field to test whether one of the
/// SHIFT modifier keys is pressed.
///
/// {@macro flutter.services.rawKeyEventDataWindows.modifiers}
/// {@template flutter.services.rawKeyEventDataWindows.modifiers}
/// Use this value if you need to decode the [modifiers] field yourself, but
/// it's much easier to use [isModifierPressed] if you just want to know if
/// a modifier is pressed.
/// {@endtemplate}
static const int modifierShift = 1 << 0;
/// This mask is used to check the [modifiers] field to test whether the left

2
packages/flutter/lib/src/widgets/basic.dart
View File

@ -5271,7 +5271,7 @@ class RichText extends MultiChildRenderObjectWidget {
/// {@macro flutter.painting.textPainter.strutStyle}
final StrutStyle strutStyle;
/// {@macro flutter.widgets.text.DefaultTextStyle.textWidthBasis}
/// {@macro flutter.painting.textPainter.textWidthBasis}
final TextWidthBasis textWidthBasis;
/// {@macro flutter.dart:ui.textHeightBehavior}

2
packages/flutter/lib/src/widgets/binding.dart
View File

@ -695,7 +695,7 @@ mixin WidgetsBinding on BindingBase, ServicesBinding, SchedulerBinding, GestureB
/// A future that completes when the Flutter engine has rasterized the first
/// frame.
///
/// {@macro flutter.frame_rasterize_vs_presented}
/// {@macro flutter.frame_rasterized_vs_presented}
///
/// See also:
///

4
packages/flutter/lib/src/widgets/editable_text.dart
View File

@ -518,7 +518,7 @@ class EditableText extends StatefulWidget {
/// {@macro flutter.dart:ui.textHeightBehavior},
final TextHeightBehavior textHeightBehavior;
/// {@macro flutter.widgets.text.DefaultTextStyle.textWidthBasis}
/// {@macro flutter.painting.textPainter.textWidthBasis}
final TextWidthBasis textWidthBasis;
/// {@template flutter.widgets.editableText.readOnly}
@ -685,6 +685,7 @@ class EditableText extends StatefulWidget {
/// See [RenderEditable.locale] for more information.
final Locale locale;
/// {@template flutter.widgets.editableText.textScaleFactor}
/// The number of font pixels for each logical pixel.
///
/// For example, if the text scale factor is 1.5, text will be 50% larger than
@ -692,6 +693,7 @@ class EditableText extends StatefulWidget {
///
/// Defaults to the [MediaQueryData.textScaleFactor] obtained from the ambient
/// [MediaQuery], or 1.0 if there is no [MediaQuery] in scope.
/// {@endtemplate}
final double textScaleFactor;
/// The color to use when painting the cursor.