Skip to content

F
Front-End
Unverified Commit 4b4287ba authored by Michael Goderbauer's avatar Michael Goderbauer Committed by GitHub
Browse files
Options

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

parent cac22cdb
Show whitespace changes
Inline Side-by-side
Showing with 104 additions and 136 deletions
dartdoc_options.yaml
View file @ 4b4287ba
......@@ -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
packages/flutter/lib/src/material/button.dart
View file @ 4b4287ba
......@@ -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
......
packages/flutter/lib/src/material/color_scheme.dart
View file @ 4b4287ba
......@@ -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),
......
packages/flutter/lib/src/material/icon_button.dart
View file @ 4b4287ba
......@@ -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;
......
packages/flutter/lib/src/material/scaffold.dart
View file @ 4b4287ba
......@@ -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.
......
packages/flutter/lib/src/material/slider_theme.dart
View file @ 4b4287ba
......@@ -15,146 +15,53 @@ import 'colors.dart';
import 'theme.dart';
import 'theme_data.dart';
/// Applies a slider theme to descendant [Slider] widgets.
///
/// A slider theme describes the colors and shape choices of the slider
/// components.
///
/// Descendant widgets obtain the current theme's [SliderThemeData] object using
/// [SliderTheme.of]. When a widget uses [SliderTheme.of], it is automatically
/// rebuilt if the theme later changes.
///
/// The slider is as big as the largest of
/// the [SliderComponentShape.getPreferredSize] of the thumb shape,
/// the [SliderComponentShape.getPreferredSize] of the overlay shape,
/// and the [SliderTickMarkShape.getPreferredSize] of the tick mark shape
///
/// See also:
///
/// * [SliderThemeData], which describes the actual configuration of a slider
/// theme.
/// {@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
/// components.
///
/// Descendant widgets obtain the current theme's [SliderThemeData] object using
/// [SliderTheme.of]. When a widget uses [SliderTheme.of], it is automatically
/// rebuilt if the theme later changes.
///
/// The slider is as big as the largest of
/// the [SliderComponentShape.getPreferredSize] of the thumb shape,
/// the [SliderComponentShape.getPreferredSize] of the overlay shape,
/// and the [SliderTickMarkShape.getPreferredSize] of the tick mark shape
///
/// See also:
///
/// * [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}
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}
///
/// {@macro flutter.material.slider.shape.sizeWithOverflow}
/// {@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.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}
......
packages/flutter/lib/src/material/text_theme.dart
View file @ 4b4287ba
......@@ -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(
......
packages/flutter/lib/src/rendering/editable.dart
View file @ 4b4287ba
......@@ -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);
......
packages/flutter/lib/src/rendering/paragraph.dart
View file @ 4b4287ba
......@@ -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);
......
packages/flutter/lib/src/services/raw_keyboard_windows.dart
View file @ 4b4287ba
......@@ -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
......
packages/flutter/lib/src/widgets/basic.dart
View file @ 4b4287ba
......@@ -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}
......
packages/flutter/lib/src/widgets/binding.dart
View file @ 4b4287ba
......@@ -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:
///
......
packages/flutter/lib/src/widgets/editable_text.dart
View file @ 4b4287ba
......@@ -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.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

HIAST - GitLab