From 9909e773dc66608a866efa7388f39127509d0e1e Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Thu, 28 Sep 2017 16:43:33 -0700 Subject: [PATCH] More documentation fixes (#12290) --- .../lib/src/cupertino/bottom_tab_bar.dart | 6 +- .../flutter/lib/src/cupertino/dialog.dart | 3 +- .../flutter/lib/src/cupertino/nav_bar.dart | 110 ++++++++++-------- .../lib/src/cupertino/page_scaffold.dart | 6 +- packages/flutter/lib/src/cupertino/route.dart | 22 ++-- .../lib/src/cupertino/tab_scaffold.dart | 17 +-- .../flutter/lib/src/cupertino/tab_view.dart | 7 +- packages/flutter/lib/src/material/app.dart | 6 +- packages/flutter/lib/src/material/arc.dart | 10 +- .../src/material/material_localizations.dart | 8 +- .../flutter/lib/src/material/typography.dart | 8 +- .../flutter/lib/src/painting/gradient.dart | 2 +- .../flutter/lib/src/painting/text_style.dart | 2 +- .../flutter/lib/src/rendering/object.dart | 16 +-- .../flutter/lib/src/rendering/paragraph.dart | 2 +- .../flutter/lib/src/rendering/proxy_box.dart | 2 +- .../lib/src/services/image_stream.dart | 10 +- packages/flutter/lib/src/widgets/app.dart | 10 +- packages/flutter/lib/src/widgets/basic.dart | 6 +- .../flutter/lib/src/widgets/framework.dart | 32 ----- .../lib/src/widgets/gesture_detector.dart | 3 +- packages/flutter/lib/src/widgets/heroes.dart | 2 +- .../lib/src/widgets/modal_barrier.dart | 52 ++++++++- packages/flutter/lib/src/widgets/routes.dart | 35 +++++- 24 files changed, 227 insertions(+), 150 deletions(-) diff --git a/packages/flutter/lib/src/cupertino/bottom_tab_bar.dart b/packages/flutter/lib/src/cupertino/bottom_tab_bar.dart index 384dcce452..62af9d46c5 100644 --- a/packages/flutter/lib/src/cupertino/bottom_tab_bar.dart +++ b/packages/flutter/lib/src/cupertino/bottom_tab_bar.dart @@ -32,8 +32,8 @@ const Color _kDefaultTabBarBorderColor = const Color(0x4C000000); /// /// See also: /// -/// * [CupertinoTabScaffold] which hosts the [CupertinoTabBar] at the bottom. -/// * [BottomNavigationBarItem] typical item in a [CupertinoTabBar]. +/// * [CupertinoTabScaffold], which hosts the [CupertinoTabBar] at the bottom. +/// * [BottomNavigationBarItem], an item in a [CupertinoTabBar]. class CupertinoTabBar extends StatelessWidget implements PreferredSizeWidget { /// Creates a tab bar in the iOS style. CupertinoTabBar({ @@ -143,7 +143,7 @@ class CupertinoTabBar extends StatelessWidget implements PreferredSizeWidget { List _buildTabItems() { final List result = []; - for (int index = 0; index < items.length; ++index) { + for (int index = 0; index < items.length; index += 1) { result.add( _wrapActiveItem( new Expanded( diff --git a/packages/flutter/lib/src/cupertino/dialog.dart b/packages/flutter/lib/src/cupertino/dialog.dart index 399e021af0..6e4a9fd7ff 100644 --- a/packages/flutter/lib/src/cupertino/dialog.dart +++ b/packages/flutter/lib/src/cupertino/dialog.dart @@ -187,7 +187,8 @@ class CupertinoAlertDialog extends StatelessWidget { /// /// See also: /// -/// * [CupertinoAlertDialog] +/// * [CupertinoAlertDialog], a dialog that informs the user about situations +/// that require acknowledgement class CupertinoDialogAction extends StatelessWidget { /// Creates an action for an iOS-style dialog. const CupertinoDialogAction({ diff --git a/packages/flutter/lib/src/cupertino/nav_bar.dart b/packages/flutter/lib/src/cupertino/nav_bar.dart index f0fa9d1f71..b774b186c2 100644 --- a/packages/flutter/lib/src/cupertino/nav_bar.dart +++ b/packages/flutter/lib/src/cupertino/nav_bar.dart @@ -9,15 +9,15 @@ import 'package:flutter/widgets.dart'; import 'colors.dart'; -/// Standard iOS nav bar height without the status bar. +/// Standard iOS navigation bar height without the status bar. const double _kNavBarPersistentHeight = 44.0; -/// Size increase from expanding the nav bar into an iOS 11 style large title +/// Size increase from expanding the navigation bar into an iOS-11-style large title /// form in a [CustomScrollView]. const double _kNavBarLargeTitleHeightExtension = 56.0; /// Number of logical pixels scrolled down before the title text is transferred -/// from the normal nav bar to a big title below the nav bar. +/// from the normal navigation bar to a big title below the navigation bar. const double _kNavBarShowLargeTitleThreshold = 10.0; const double _kNavBarEdgePadding = 16.0; @@ -50,15 +50,12 @@ const TextStyle _kLargeTitleTextStyle = const TextStyle( /// If the given [backgroundColor]'s opacity is not 1.0 (which is the case by /// default), it will produce a blurring effect to the content behind it. /// -/// Enabling [largeTitle] will create a scrollable second row showing the title -/// in a larger font introduced in iOS 11. The [middle] widget must be a text -/// and the [CupertinoNavigationBar] must be placed in a sliver group in this case. -/// /// See also: /// -/// * [CupertinoPageScaffold] page layout helper typically hosting the [CupertinoNavigationBar]. -/// * [CupertinoSliverNavigationBar] for a nav bar to be placed in a sliver and -/// that supports iOS 11 style large titles. +/// * [CupertinoPageScaffold], a page layout helper typically hosting the +/// [CupertinoNavigationBar]. +/// * [CupertinoSliverNavigationBar] for a navigation bar to be placed in a +/// scrolling list and that supports iOS-11-style large titles. // // TODO(xster): document automatic addition of a CupertinoBackButton. // TODO(xster): add sample code using icons. @@ -74,33 +71,33 @@ class CupertinoNavigationBar extends StatelessWidget implements PreferredSizeWid }) : assert(middle != null, 'There must be a middle widget, usually a title.'), super(key: key); - /// Widget to place at the start of the nav bar. Normally a back button + /// Widget to place at the start of the navigation bar. Normally a back button /// for a normal page or a cancel button for full page dialogs. final Widget leading; - /// Widget to place in the middle of the nav bar. Normally a title or + /// Widget to place in the middle of the navigation bar. Normally a title or /// a segmented control. final Widget middle; - /// Widget to place at the end of the nav bar. Normally additional actions + /// Widget to place at the end of the navigation bar. Normally additional actions /// taken on the page such as a search or edit function. final Widget trailing; - // TODO(xster): implement support for double row nav bars. + // TODO(xster): implement support for double row navigation bars. - /// The background color of the nav bar. If it contains transparency, the + /// The background color of the navigation bar. If it contains transparency, the /// tab bar will automatically produce a blurring effect to the content /// behind it. final Color backgroundColor; /// Default color used for text and icons of the [leading] and [trailing] - /// widgets in the nav bar. + /// widgets in the navigation bar. /// /// The default color for text in the [middle] slot is always black, as per /// iOS standard design. final Color actionsForegroundColor; - /// True if the nav bar's background color has no transparency. + /// True if the navigation bar's background color has no transparency. bool get opaque => backgroundColor.alpha == 0xFF; @override @@ -122,30 +119,32 @@ class CupertinoNavigationBar extends StatelessWidget implements PreferredSizeWid } } -/// An iOS-styled navigation bar with iOS 11 style large titles using slivers. +/// An iOS-styled navigation bar with iOS-11-style large titles using slivers. /// /// The [CupertinoSliverNavigationBar] must be placed in a sliver group such /// as the [CustomScrollView]. /// -/// This navigation bar consists of 2 sections, a pinned static section built -/// using [CupertinoNavigationBar] on top and a sliding section containing -/// iOS 11 style large titles below it. +/// This navigation bar consists of two sections, a pinned static section on top +/// and a sliding section containing iOS-11-style large title below it. /// /// It should be placed at top of the screen and automatically accounts for -/// the OS's status bar. +/// the iOS status bar. /// -/// Minimally, a [largeTitle] [Text] will appear in the middle of the app bar -/// when the sliver is collapsed and transfer to the slidable below in larger font +/// Minimally, a [largeTitle] widget will appear in the middle of the app bar +/// when the sliver is collapsed and transfer to the area below in larger font /// when the sliver is expanded. /// -/// For advanced uses, an optional [middle] widget can be supplied to show a different -/// widget in the middle of the nav bar when the sliver is collapsed. +/// For advanced uses, an optional [middle] widget can be supplied to show a +/// different widget in the middle of the navigation bar when the sliver is collapsed. /// /// See also: /// -/// * [CupertinoNavigationBar] a static iOS nav bar that doesn't have a slidable -/// large title section. +/// * [CupertinoNavigationBar], an iOS navigation bar for use on non-scrolling +/// pages. class CupertinoSliverNavigationBar extends StatelessWidget { + /// Creates a navigation bar for scrolling lists. + /// + /// The [largeTitle] argument is required and must not be null. const CupertinoSliverNavigationBar({ Key key, @required this.largeTitle, @@ -154,48 +153,58 @@ class CupertinoSliverNavigationBar extends StatelessWidget { this.trailing, this.backgroundColor: _kDefaultNavBarBackgroundColor, this.actionsForegroundColor: CupertinoColors.activeBlue, - }) : assert(largeTitle != null, 'There must be a largeTitle Text'), + }) : assert(largeTitle != null), super(key: key); /// The navigation bar's title. /// /// This text will appear in the top static navigation bar when collapsed and - /// in the bottom slidable in a larger font when expanded. - final Text largeTitle; + /// below the navigation bar, in a larger font, when expanded. + /// + /// A suitable [DefaultTextStyle] is provided around this widget as it is + /// moved around, to change its font size. + /// + /// If [middle] is null, then the [largeTitle] widget will be inserted into + /// the tree in two places when transitioning from the collapsed state to the + /// expanded state. It is therefore imperative that this subtree not contain + /// any [GlobalKey]s, and that it not rely on maintaining state (for example, + /// animations will not survive the transition from one location to the other, + /// and may in fact be visible in two places at once during the transition). + final Widget largeTitle; - /// Widget to place at the start of the static nav bar. Normally a back button + /// Widget to place at the start of the static navigation bar. Normally a back button /// for a normal page or a cancel button for full page dialogs. /// /// This widget is visible in both collapsed and expanded states. final Widget leading; - /// An override widget to place in the middle of the static nav bar. + /// A widget to place in the middle of the static navigation bar instead of + /// the [largeTitle]. /// /// This widget is visible in both collapsed and expanded states. The text - /// supplied in [largeTitle] will no longer appear in collapsed state. + /// supplied in [largeTitle] will no longer appear in collapsed state if a + /// [middle] widget is provided. final Widget middle; - /// Widget to place at the end of the static nav bar. Normally additional actions - /// taken on the page such as a search or edit function. + /// Widget to place at the end of the static navigation bar. Normally + /// additional actions taken on the page such as a search or edit function. /// /// This widget is visible in both collapsed and expanded states. final Widget trailing; - // TODO(xster): implement support for double row nav bars. - - /// The background color of the nav bar. If it contains transparency, the + /// The background color of the navigation bar. If it contains transparency, the /// tab bar will automatically produce a blurring effect to the content /// behind it. final Color backgroundColor; /// Default color used for text and icons of the [leading] and [trailing] - /// widgets in the nav bar. + /// widgets in the navigation bar. /// /// The default color for text in the [middle] slot is always black, as per /// iOS standard design. final Color actionsForegroundColor; - /// True if the nav bar's background color has no transparency. + /// True if the navigation bar's background color has no transparency. bool get opaque => backgroundColor.alpha == 0xFF; @override @@ -243,9 +252,9 @@ Widget _wrapWithBackground({Color backgroundColor, Widget child}) { ); } -/// The top part of the nav bar that's never scrolled away. +/// The top part of the navigation bar that's never scrolled away. /// -/// Consists of the entire nav bar without background and border when used +/// Consists of the entire navigation bar without background and border when used /// without large titles. With large titles, it's the top static half that /// doesn't scroll. class _CupertinoPersistentNavigationBar extends StatelessWidget implements PreferredSizeWidget { @@ -353,7 +362,7 @@ class _CupertinoLargeTitleNavigationBarSliverDelegate extends SliverPersistentHe final double persistentHeight; - final Text title; + final Widget title; final Widget leading; @@ -436,11 +445,12 @@ class _CupertinoLargeTitleNavigationBarSliverDelegate extends SliverPersistentHe @override bool shouldRebuild(_CupertinoLargeTitleNavigationBarSliverDelegate oldDelegate) { - return persistentHeight != oldDelegate.persistentHeight || - leading != oldDelegate.leading || - middle != oldDelegate.middle || - trailing != oldDelegate.trailing || - backgroundColor != oldDelegate.backgroundColor || - actionsForegroundColor != oldDelegate.actionsForegroundColor; + return persistentHeight != oldDelegate.persistentHeight + || title != oldDelegate.title + || leading != oldDelegate.leading + || middle != oldDelegate.middle + || trailing != oldDelegate.trailing + || backgroundColor != oldDelegate.backgroundColor + || actionsForegroundColor != oldDelegate.actionsForegroundColor; } } diff --git a/packages/flutter/lib/src/cupertino/page_scaffold.dart b/packages/flutter/lib/src/cupertino/page_scaffold.dart index c699032ef1..4a71147e6b 100644 --- a/packages/flutter/lib/src/cupertino/page_scaffold.dart +++ b/packages/flutter/lib/src/cupertino/page_scaffold.dart @@ -15,9 +15,11 @@ import 'nav_bar.dart'; /// /// See also: /// -/// * [CupertinoPageRoute] a modal page route that typically hosts a [CupertinoPageRoute] -/// with support for iOS style page transitions. +/// * [CupertinoTabScaffold], a similar widget for tabbed applications. +/// * [CupertinoPageRoute], a modal page route that typically hosts a +/// [CupertinoPageScaffold] with support for iOS-style page transitions. class CupertinoPageScaffold extends StatelessWidget { + /// Creates a layout for pages with a navigation bar at the top. const CupertinoPageScaffold({ Key key, this.navigationBar, diff --git a/packages/flutter/lib/src/cupertino/route.dart b/packages/flutter/lib/src/cupertino/route.dart index 9e6d4d297e..28fcfb3d99 100644 --- a/packages/flutter/lib/src/cupertino/route.dart +++ b/packages/flutter/lib/src/cupertino/route.dart @@ -67,10 +67,12 @@ final DecorationTween _kGradientShadowTween = new DecorationTween( /// /// See also: /// -/// * [MaterialPageRoute] for an adaptive [PageRoute] that uses a platform -/// appropriate transition. -/// * [CupertinoPageScaffold] typical content of a [CupertinoPageRoute] implementing -/// iOS style layout with navigation bar on top. +/// * [MaterialPageRoute], for an adaptive [PageRoute] that uses a +/// platform-appropriate transition. +/// * [CupertinoPageScaffold], for applications that have one page with a fixed +/// navigation bar on top. +/// * [CupertinoTabScaffold], for applications that have a tab bar at the +/// bottom with multiple pages. class CupertinoPageRoute extends PageRoute { /// Creates a page route for use in an iOS designed app. /// @@ -146,9 +148,9 @@ class CupertinoPageRoute extends PageRoute { /// Whether a pop gesture is currently underway. /// - /// This starts returning true when the [startPopGesture] method returns a new - /// [NavigationGestureController]. It returns false if that has not yet - /// occurred or if the most recent such gesture has completed. + /// This starts returning true when pop gesture is started by the user. It + /// returns false if that has not yet occurred or if the most recent such + /// gesture has completed. /// /// See also: /// @@ -156,12 +158,14 @@ class CupertinoPageRoute extends PageRoute { /// in the first place. bool get popGestureInProgress => _backGestureController != null; - /// Whether a pop gesture will be considered acceptable by [startPopGesture]. + /// Whether a pop gesture can be started by the user. /// /// This returns true if the user can edge-swipe to a previous route, /// otherwise false. /// - /// This will return false if [popGestureInProgress] is true. + /// This will return false once [popGestureInProgress] is true, but + /// [popGestureInProgress] can only become true if [popGestureEnabled] was + /// true first. /// /// This should only be used between frames, not during build. bool get popGestureEnabled { diff --git a/packages/flutter/lib/src/cupertino/tab_scaffold.dart b/packages/flutter/lib/src/cupertino/tab_scaffold.dart index 75775c3684..53d9603651 100644 --- a/packages/flutter/lib/src/cupertino/tab_scaffold.dart +++ b/packages/flutter/lib/src/cupertino/tab_scaffold.dart @@ -16,9 +16,9 @@ import 'bottom_tab_bar.dart'; /// to change the active tab. /// /// Tabs' contents are built with the provided [tabBuilder] at the active -/// tab index. [tabBuilder] must be able to build the same number of -/// pages as the [tabBar.items.length]. Inactive tabs will be moved [Offstage] -/// and its animations disabled. +/// tab index. The [tabBuilder] must be able to build the same number of +/// pages as there are [tabBar.items]. Inactive tabs will be moved [Offstage] +/// and their animations disabled. /// /// Use [CupertinoTabView] as the content of each tab to support tabs with parallel /// navigation state and history. @@ -74,13 +74,16 @@ import 'bottom_tab_bar.dart'; /// /// See also: /// -/// * [CupertinoTabBar] bottom tab bars inserted in the scaffold. -/// * [CupertinoTabView] a typical root content of each tap that holds its own +/// * [CupertinoTabBar], the bottom tab bar inserted in the scaffold. +/// * [CupertinoTabView], the typical root content of each tab that holds its own /// [Navigator] stack. -/// * [CupertinoPageRoute] a route hosting modal pages with iOS style transitions. -/// * [CupertinoPageScaffold] typical contents of an iOS modal page implementing +/// * [CupertinoPageRoute], a route hosting modal pages with iOS style transitions. +/// * [CupertinoPageScaffold], typical contents of an iOS modal page implementing /// layout with a navigation bar on top. class CupertinoTabScaffold extends StatefulWidget { + /// Creates a layout for applications with a tab bar at the bottom. + /// + /// The [tabBar] and [tabBuilder] arguments must not be null. const CupertinoTabScaffold({ Key key, @required this.tabBar, diff --git a/packages/flutter/lib/src/cupertino/tab_view.dart b/packages/flutter/lib/src/cupertino/tab_view.dart index 8757210642..e452467fca 100644 --- a/packages/flutter/lib/src/cupertino/tab_view.dart +++ b/packages/flutter/lib/src/cupertino/tab_view.dart @@ -31,10 +31,11 @@ import 'route.dart'; /// /// See also: /// -/// * [CupertinoTabScaffold] a typical host that supports switching between tabs. -/// * [CupertinoPageRoute] a typical modal page route pushed onto the [CupertinoTabView]'s -/// [Navigator]. +/// * [CupertinoTabScaffold], a typical host that supports switching between tabs. +/// * [CupertinoPageRoute], a typical modal page route pushed onto the +/// [CupertinoTabView]'s [Navigator]. class CupertinoTabView extends StatelessWidget { + /// Creates the content area for a tab in a [CupertinoTabScaffold]. const CupertinoTabView({ Key key, this.builder, diff --git a/packages/flutter/lib/src/material/app.dart b/packages/flutter/lib/src/material/app.dart index edd2a69644..78c0a36c81 100644 --- a/packages/flutter/lib/src/material/app.dart +++ b/packages/flutter/lib/src/material/app.dart @@ -148,7 +148,7 @@ class MaterialApp extends StatefulWidget { /// If non-null this function is called to produce the app's /// title string, otherwise [title] is used. /// - /// The [onGenerateTitle] `context` parameter includes the [WidgetApp]'s + /// The [onGenerateTitle] `context` parameter includes the [WidgetsApp]'s /// [Localizations] widget so that this callback can be used to produce a /// localized title. /// @@ -260,9 +260,9 @@ class MaterialApp extends StatefulWidget { /// Delegates that produce [WidgetsLocalizations] and [MaterialLocalizations] /// are included automatically. Apps can provide their own versions of these /// localizations by creating implementations of - /// [LocalizationsDelegate] or + /// [LocalizationsDelegate] or /// [LocalizationsDelegate] whose load methods return - /// custom versions of [WidgetLocalizations] or [MaterialLocalizations]. + /// custom versions of [WidgetsLocalizations] or [MaterialLocalizations]. /// /// For example: to add support to [MaterialLocalizations] for a /// locale it doesn't already support, say `const Locale('foo', 'BR')`, diff --git a/packages/flutter/lib/src/material/arc.dart b/packages/flutter/lib/src/material/arc.dart index 49ed98002a..9fac0327d3 100644 --- a/packages/flutter/lib/src/material/arc.dart +++ b/packages/flutter/lib/src/material/arc.dart @@ -328,9 +328,9 @@ class MaterialRectArcTween extends RectTween { } } -/// A [Tween] that interpolates a [Rect] by moving it along a circular -/// arc from [begin.center] to [end.center] while interpoloting the rectangle's -/// width and height. +/// A [Tween] that interpolates a [Rect] by moving it along a circular arc from +/// [begin]'s [Rect.center] to [end]'s [Rect.center] while interpolating the +/// rectangle's width and height. /// /// The arc that defines that center of the interpolated rectangle as it morphs /// from [begin] to [end] is a [MaterialPointArcTween]. @@ -367,8 +367,8 @@ class MaterialRectCenterArcTween extends RectTween { _dirty = false; } - /// If [begin] and [end] are non-null, returns a tween that interpolates - /// along a circular arc between [begin.center] and [end.center]. + /// If [begin] and [end] are non-null, returns a tween that interpolates along + /// a circular arc between [begin]'s [Rect.center] and [end]'s [Rect.center]. MaterialPointArcTween get centerArc { if (begin == null || end == null) return null; diff --git a/packages/flutter/lib/src/material/material_localizations.dart b/packages/flutter/lib/src/material/material_localizations.dart index e2781eb016..fc6041c6da 100644 --- a/packages/flutter/lib/src/material/material_localizations.dart +++ b/packages/flutter/lib/src/material/material_localizations.dart @@ -34,10 +34,10 @@ abstract class MaterialLocalizations { /// The tooltip for the [MonthPicker]'s "previous month" button. String get previousMonthTooltip; - /// The tooltip for the [PaginatedDataTables]'s "next page" button. + /// The tooltip for the [PaginatedDataTable]'s "next page" button. String get nextPageTooltip; - /// The tooltip for the [PaginatedDataTables]'s "previous page" button. + /// The tooltip for the [PaginatedDataTable]'s "previous page" button. String get previousPageTooltip; /// The default [PopupMenuButton] tooltip. @@ -55,7 +55,7 @@ abstract class MaterialLocalizations { /// Title for the [PaginatedDataTable]'s "rows per page" footer. String get rowsPerPageTitle; - /// Title for the PaginatedDataTable's selected row count header. + /// Title for the [PaginatedDataTable]'s selected row count header. String selectedRowCountTitle(int selectedRowCount); /// Label for "cancel" buttons and menu items. @@ -82,7 +82,7 @@ abstract class MaterialLocalizations { /// Label for "select all" edit buttons and menu items. String get selectAllButtonLabel; - /// Label for the [AboutBox] button that shows the [LicensePage]. + /// Label for the [AboutDialog] button that shows the [LicensePage]. String get viewLicensesButtonLabel; /// The abbreviation for ante meridiem (before noon) shown in the time picker. diff --git a/packages/flutter/lib/src/material/typography.dart b/packages/flutter/lib/src/material/typography.dart index 568fe0f7c5..dd3a6e498a 100644 --- a/packages/flutter/lib/src/material/typography.dart +++ b/packages/flutter/lib/src/material/typography.dart @@ -34,7 +34,7 @@ import 'colors.dart'; /// * @immutable class TextTheme { - /// Create a text theme that uses the given values. + /// Creates a text theme that uses the given values. /// /// Rather than creating a new text theme, consider using [Typography.black] /// or [Typography.white], which implement the typography styles in the @@ -131,6 +131,12 @@ class TextTheme { ); } + /// Creates a new [TextTheme] where each text style from this object has been + /// merged with the matching text style from the `other` object. + /// + /// This is particularly useful if one [TextTheme] defines one set of + /// properties and another defines a different set, e.g. having colors defined + /// in one text theme and font sizes in another. TextTheme merge(TextTheme other) { if (other == null) return this; diff --git a/packages/flutter/lib/src/painting/gradient.dart b/packages/flutter/lib/src/painting/gradient.dart index bad1dbe188..b84f058569 100644 --- a/packages/flutter/lib/src/painting/gradient.dart +++ b/packages/flutter/lib/src/painting/gradient.dart @@ -27,7 +27,7 @@ abstract class Gradient { /// Creates a [Shader] for this gradient to fill the given rect. /// /// If the gradient's configuration is text-direction-dependent, for example - /// it uses [FractionalOffsetDirection] objects instead of [FractionalOffset] + /// it uses [FractionalOffsetDirectional] objects instead of [FractionalOffset] /// objects, then the `textDirection` argument must not be null. Shader createShader(Rect rect, { TextDirection textDirection }); } diff --git a/packages/flutter/lib/src/painting/text_style.dart b/packages/flutter/lib/src/painting/text_style.dart index 15058c8af7..c842546fdc 100644 --- a/packages/flutter/lib/src/painting/text_style.dart +++ b/packages/flutter/lib/src/painting/text_style.dart @@ -145,7 +145,7 @@ import 'basic_types.dart'; /// /// The `family` property determines the name of the font, which you can use in /// the [fontFamily] argument. The `asset` property is a path to the font file, -/// relative to the [pubspec.yaml] file. The `weight` property specifies the +/// relative to the `pubspec.yaml` file. The `weight` property specifies the /// weight of the glyph outlines in the file as an integer multiple of 100 /// between 100 and 900. This corresponds to the [FontWeight] class and can be /// used in the [fontWeight] argument. The `style` property specfies whether the diff --git a/packages/flutter/lib/src/rendering/object.dart b/packages/flutter/lib/src/rendering/object.dart index 931e6fcf93..634fea6ca6 100644 --- a/packages/flutter/lib/src/rendering/object.dart +++ b/packages/flutter/lib/src/rendering/object.dart @@ -2560,31 +2560,31 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im /// Mark this node as needing an update to its semantics description. /// - /// The parameters [onlyLocalUpdates] and [noGeometry] tell the framework + /// The parameters `onlyLocalUpdates` and `noGeometry` tell the framework /// how much of the semantics have changed. Bigger changes (indicated by /// setting one or both parameters to false) are more expansive to compute. /// - /// [onlyLocalUpdates] should be set to true to reduce cost if the semantics + /// `onlyLocalUpdates` should be set to true to reduce cost if the semantics /// update does not in any way change the shape of the semantics tree (e.g. /// [SemanticsNode]s will neither be added/removed from the tree nor be moved - /// within the tree). In other words, with [onlyLocalChanges] the + /// within the tree). In other words, with `onlyLocalUpdates` the /// [RenderObject] can indicate that it only wants to perform updates on the /// local [SemanticsNode] (e.g. changing a label or flag) without affecting /// other nodes in the tree. /// - /// [onlyLocalUpdates] has to be set to false in the following cases as they + /// `onlyLocalUpdates` has to be set to false in the following cases as they /// will change the shape of the tree: /// /// 1. [isSemanticBoundary] changed its value. /// 2. [semanticsAnnotator] changed from or to returning null and /// [isSemanticBoundary] isn't true. /// - /// [noGeometry] should be set to true to reduce cost if the geometry (e.g. + /// `noGeometry` should be set to true to reduce cost if the geometry (e.g. /// size and position) of the corresponding [SemanticsNode] has not /// changed. Examples for such semantic updates that don't require a geometry /// update are changes to flags, labels, or actions. /// - /// If [onlyLocalUpdates] or [noGeometry] are incorrectly set to true, asserts + /// If `onlyLocalUpdates` or `noGeometry` are incorrectly set to true, asserts /// might throw or the computed semantics tree might be out-of-date without /// warning. void markNeedsSemanticsUpdate({ bool onlyLocalUpdates: false, bool noGeometry: false }) { @@ -2778,9 +2778,9 @@ abstract class RenderObject extends AbstractNode with DiagnosticableTreeMixin im /// By default, the method will annotate [node] with the [semanticsAnnotator] /// and add the [children] to it. /// - /// Subclasses can override this method to add additional [SemanticNode]s + /// Subclasses can override this method to add additional [SemanticsNode]s /// to the tree. If a subclass adds additional nodes in this method, it also - /// needs to override [resetSemantics] to call [SemanticsNodes.reset] on those + /// needs to override [resetSemantics] to call [SemanticsNode.reset] on those /// additional [SemanticsNode]s. void assembleSemanticsNode(SemanticsNode node, Iterable children) { assert(node == _semantics); diff --git a/packages/flutter/lib/src/rendering/paragraph.dart b/packages/flutter/lib/src/rendering/paragraph.dart index 03091f0a48..85cd1c3c39 100644 --- a/packages/flutter/lib/src/rendering/paragraph.dart +++ b/packages/flutter/lib/src/rendering/paragraph.dart @@ -237,7 +237,7 @@ class RenderParagraph extends RenderBox { bool _hasVisualOverflow = false; ui.Shader _overflowShader; - /// Whether this paragraph currently has a [ui.Shader] for its overflow + /// Whether this paragraph currently has a [dart:ui.Shader] for its overflow /// effect. /// /// Used to test this object. Not for use in production. diff --git a/packages/flutter/lib/src/rendering/proxy_box.dart b/packages/flutter/lib/src/rendering/proxy_box.dart index 17f51be1c9..56b95a59ad 100644 --- a/packages/flutter/lib/src/rendering/proxy_box.dart +++ b/packages/flutter/lib/src/rendering/proxy_box.dart @@ -2869,7 +2869,7 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticsA /// /// As an example, a [RenderSliver] that stays on the screen within a /// [Scrollable] even though the user has scrolled past it (e.g. a pinned app - /// bar) can tag its [SemanticNode] with [excludeFromScrolling] to indicate + /// bar) can tag its [SemanticsNode] with [excludeFromScrolling] to indicate /// that it should no longer be considered for semantic actions related to /// scrolling. static const SemanticsTag excludeFromScrolling = const SemanticsTag('RenderSemanticsGestureHandler.excludeFromScrolling'); diff --git a/packages/flutter/lib/src/services/image_stream.dart b/packages/flutter/lib/src/services/image_stream.dart index 7b9f92bc4d..f3d27e1357 100644 --- a/packages/flutter/lib/src/services/image_stream.dart +++ b/packages/flutter/lib/src/services/image_stream.dart @@ -7,7 +7,7 @@ import 'dart:ui' as ui show Image; import 'package:flutter/foundation.dart'; -/// A [ui.Image] object with its corresponding scale. +/// A [dart:ui.Image] object with its corresponding scale. /// /// ImageInfo objects are used by [ImageStream] objects to represent the /// actual data of the image once it has been obtained. @@ -33,7 +33,7 @@ class ImageInfo { /// /// For example, if this is 2.0 it means that there are four image pixels for /// every one logical pixel, and the image's actual width and height (as given - /// by the [ui.Image.width] and [ui.Image.height] properties) are double the + /// by the [dart:ui.Image.width] and [dart:ui.Image.height] properties) are double the /// height and width that should be used when painting the image (e.g. in the /// arguments given to [Canvas.drawImage]). final double scale; @@ -56,7 +56,7 @@ typedef void ImageListener(ImageInfo image, bool synchronousCall); /// A handle to an image resource. /// -/// ImageStream represents a handle to a [ui.Image] object and its scale +/// ImageStream represents a handle to a [dart:ui.Image] object and its scale /// (together represented by an [ImageInfo] object). The underlying image object /// might change over time, either because the image is animating or because the /// underlying image resource was mutated. @@ -164,7 +164,7 @@ class ImageStream extends Diagnosticable { } } -/// Base class for those that manage the loading of [ui.Image] objects for +/// Base class for those that manage the loading of [dart:ui.Image] objects for /// [ImageStream]s. /// /// This class is rarely used directly. Generally, an [ImageProvider] subclass @@ -243,7 +243,7 @@ class ImageStreamCompleter extends Diagnosticable { } } -/// Manages the loading of [ui.Image] objects for static [ImageStream]s (those +/// Manages the loading of [dart:ui.Image] objects for static [ImageStream]s (those /// with only one frame). class OneFrameImageStreamCompleter extends ImageStreamCompleter { /// Creates a manager for one-frame [ImageStream]s. diff --git a/packages/flutter/lib/src/widgets/app.dart b/packages/flutter/lib/src/widgets/app.dart index b97ff6ea74..c3cea17102 100644 --- a/packages/flutter/lib/src/widgets/app.dart +++ b/packages/flutter/lib/src/widgets/app.dart @@ -31,13 +31,13 @@ export 'dart:ui' show Locale; /// /// The `locale` is the device's locale when the app started, or the device /// locale the user selected after the app was started. The `supportedLocales` -/// parameter is just the value of [WidgetApp.supportedLocales]. +/// parameter is just the value of [WidgetsApp.supportedLocales]. typedef Locale LocaleResolutionCallback(Locale locale, Iterable supportedLocales); /// The signature of [WidgetsApp.onGenerateTitle]. /// /// Used to generate a value for the app's [Title.title], which the device uses -/// to identify the app for the user. The `context` includes the [WidgetApp]'s +/// to identify the app for the user. The `context` includes the [WidgetsApp]'s /// [Localizations] widget so that this method can be used to produce a /// localized title. /// @@ -123,7 +123,7 @@ class WidgetsApp extends StatefulWidget { /// If non-null this callback function is called to produce the app's /// title string, otherwise [title] is used. /// - /// The [onGenerateTitle] `context` parameter includes the [WidgetApp]'s + /// The [onGenerateTitle] `context` parameter includes the [WidgetsApp]'s /// [Localizations] widget so that this callback can be used to produce a /// localized title. /// @@ -208,7 +208,7 @@ class WidgetsApp extends StatefulWidget { /// If the callback is null or if it returns null then the resolved locale is: /// /// - The callback's `locale` parameter if it's equal to a supported locale. - /// - The first supported locale with the same [Locale.langaugeCode] as the + /// - The first supported locale with the same [Locale.languageCode] as the /// callback's `locale` parameter. /// - The first locale in [supportedLocales]. /// @@ -240,7 +240,7 @@ class WidgetsApp extends StatefulWidget { /// * [localeResolutionCallback], an app callback that resolves the app's locale /// when the device's locale changes. /// - /// * [localizationDelegates], which collectively define all of the localized + /// * [localizationsDelegates], which collectively define all of the localized /// resources used by this app. final Iterable supportedLocales; diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart index 9dba5315a9..7cff47b30e 100644 --- a/packages/flutter/lib/src/widgets/basic.dart +++ b/packages/flutter/lib/src/widgets/basic.dart @@ -2330,7 +2330,7 @@ class Positioned extends ParentDataWidget { /// See also: /// /// * [Positioned.directional], which specifies the widget's horizontal - /// position using [start] and [end] rather than [left] and [right]. + /// position using `start` and `end` rather than `left` and `right`. const Positioned({ Key key, this.left, @@ -3049,7 +3049,7 @@ class Row extends Flex { /// any. If there is no ambient directionality, and a text direction is going /// to be necessary to determine the layout order (which is always the case /// unless the row has no children or only one child) or to disambiguate - /// `start` or `end` values for the [mainAxisDirection], the [textDirection] + /// `start` or `end` values for the [mainAxisAlignment], the [textDirection] /// must not be null. Row({ Key key, @@ -3239,7 +3239,7 @@ class Column extends Flex { /// The [textDirection] argument defaults to the ambient [Directionality], if /// any. If there is no ambient directionality, and a text direction is going /// to be necessary to disambiguate `start` or `end` values for the - /// [crossAxisDirection], the [textDirection] must not be null. + /// [crossAxisAlignment], the [textDirection] must not be null. Column({ Key key, MainAxisAlignment mainAxisAlignment: MainAxisAlignment.start, diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 52aa35b31b..f04545f50e 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -1353,21 +1353,6 @@ abstract class State extends Diagnosticable { @mustCallSuper void didChangeDependencies() { } - /// Add additional properties to the given description used by - /// [toDiagnosticsNode], [toString] and [toStringDeep]. - /// - /// This method makes it easier for subclasses to coordinate to provide - /// high-quality diagnostic data. The [toString] implementation on - /// the [State] base class calls [debugFillProperties] to collect useful - /// information from subclasses to incorporate into its return value. - /// - /// If you override this, make sure to start your method with a call to - /// `super.debugFillProperties(description)`. - /// - /// See also: - /// - /// * [DiagnosticableTree.debugFillProperties], which provides detailed - /// best practices for defining diagnostic properties. @override void debugFillProperties(DiagnosticPropertiesBuilder description) { super.debugFillProperties(description); @@ -3332,23 +3317,6 @@ abstract class Element extends DiagnosticableTree implements BuildContext { return widget != null ? '${widget.toStringShort()}' : '[$runtimeType]'; } - /// Add additional properties to the given description used by - /// [toDiagnosticsNode], [toString] and [toStringDeep]. - /// - /// This method makes it easier for subclasses to coordinate to provide - /// high-quality diagnostic data. The [toString] implementation on - /// the [State] base class calls [debugFillProperties] to collect useful - /// information from subclasses to incorporate into its return value. - /// - /// If you override this, make sure to start your method with a call to - /// `super.debugFillProperties(description)`. - /// - /// See also: - /// - /// * [DiagnosticableTree.debugFillProperties], which provides detailed - /// best practices for defining diagnostic properties. - @protected - @mustCallSuper @override void debugFillProperties(DiagnosticPropertiesBuilder description) { super.debugFillProperties(description); diff --git a/packages/flutter/lib/src/widgets/gesture_detector.dart b/packages/flutter/lib/src/widgets/gesture_detector.dart index 527d09cf4a..7273be6af9 100644 --- a/packages/flutter/lib/src/widgets/gesture_detector.dart +++ b/packages/flutter/lib/src/widgets/gesture_detector.dart @@ -567,7 +567,8 @@ class RawGestureDetectorState extends State { /// The event can be interpreted by assistive technologies to provide /// additional feedback to the user about the state of the UI. /// - /// The event will not be sent if [excludeFromSemantics] is set to true. + /// The event will not be sent if [RawGestureDetector.excludeFromSemantics] is + /// set to true. void sendSemanticsEvent(SemanticsEvent event) { if (!widget.excludeFromSemantics) { final RenderSemanticsGestureHandler semanticsGestureHandler = context.findRenderObject(); diff --git a/packages/flutter/lib/src/widgets/heroes.dart b/packages/flutter/lib/src/widgets/heroes.dart index cc7b6ad7bf..5635724f5c 100644 --- a/packages/flutter/lib/src/widgets/heroes.dart +++ b/packages/flutter/lib/src/widgets/heroes.dart @@ -101,7 +101,7 @@ class Hero extends StatefulWidget { /// /// If this property is null, the default, then the value of /// [HeroController.createRectTween] is used. The [HeroController] created by - /// [MaterialApp] creates a [MaterialArcRectTween]. + /// [MaterialApp] creates a [MaterialRectAreTween]. final CreateRectTween createRectTween; /// The widget subtree that will "fly" from one route to another during a diff --git a/packages/flutter/lib/src/widgets/modal_barrier.dart b/packages/flutter/lib/src/widgets/modal_barrier.dart index 602e19ba83..36e23e2041 100644 --- a/packages/flutter/lib/src/widgets/modal_barrier.dart +++ b/packages/flutter/lib/src/widgets/modal_barrier.dart @@ -12,6 +12,19 @@ import 'navigator.dart'; import 'transitions.dart'; /// A widget that prevents the user from interacting with widgets behind itself. +/// +/// The modal barrier is the scrim that is rendered behind each route, which +/// generally prevents the user from interacting with the route below the +/// current route, and normally partially obscures such routes. +/// +/// For example, when a dialog is on the screen, the page below the dialog is +/// usually darkened by the modal barrier. +/// +/// See also: +/// +/// * [ModalRoute], which indirectly uses this widget. +/// * [AnimatedModalBarrier], which is similar but takes an animated [color] +/// instead of a single color value. class ModalBarrier extends StatelessWidget { /// Creates a widget that blocks user interaction. const ModalBarrier({ @@ -21,9 +34,19 @@ class ModalBarrier extends StatelessWidget { }) : super(key: key); /// If non-null, fill the barrier with this color. + /// + /// See also: + /// + /// * [ModalRoute.barrierColor], which controls this property for the + /// [ModalBarrier] built by [ModalRoute] pages. final Color color; /// Whether touching the barrier will pop the current route off the [Navigator]. + /// + /// See also: + /// + /// * [ModalRoute.barrierDismissible], which controls this property for the + /// [ModalBarrier] built by [ModalRoute] pages. final bool dismissible; @override @@ -55,7 +78,22 @@ class ModalBarrier extends StatelessWidget { } } -/// A widget that prevents the user from interacting with widgets behind itself. +/// A widget that prevents the user from interacting with widgets behind itself, +/// and can be configured with an animated color value. +/// +/// The modal barrier is the scrim that is rendered behind each route, which +/// generally prevents the user from interacting with the route below the +/// current route, and normally partially obscures such routes. +/// +/// For example, when a dialog is on the screen, the page below the dialog is +/// usually darkened by the modal barrier. +/// +/// This widget is similar to [ModalBarrier] except that it takes an animated +/// [color] instead of a single color. +/// +/// See also: +/// +/// * [ModalRoute], which uses this widget. class AnimatedModalBarrier extends AnimatedWidget { /// Creates a widget that blocks user interaction. const AnimatedModalBarrier({ @@ -65,16 +103,26 @@ class AnimatedModalBarrier extends AnimatedWidget { }) : super(key: key, listenable: color); /// If non-null, fill the barrier with this color. + /// + /// See also: + /// + /// * [ModalRoute.barrierColor], which controls this property for the + /// [AnimatedModalBarrier] built by [ModalRoute] pages. Animation get color => listenable; /// Whether touching the barrier will pop the current route off the [Navigator]. + /// + /// See also: + /// + /// * [ModalRoute.barrierDismissible], which controls this property for the + /// [AnimatedModalBarrier] built by [ModalRoute] pages. final bool dismissible; @override Widget build(BuildContext context) { return new ModalBarrier( color: color?.value, - dismissible: dismissible + dismissible: dismissible, ); } } diff --git a/packages/flutter/lib/src/widgets/routes.dart b/packages/flutter/lib/src/widgets/routes.dart index 7d48046212..c0b1a4e677 100644 --- a/packages/flutter/lib/src/widgets/routes.dart +++ b/packages/flutter/lib/src/widgets/routes.dart @@ -518,7 +518,7 @@ abstract class ModalRoute extends TransitionRoute with LocalHistoryRoute of(BuildContext context) { final _ModalScopeStatus widget = context.inheritFromWidgetOfExactType(_ModalScopeStatus); return widget?.route; @@ -736,13 +736,46 @@ abstract class ModalRoute extends TransitionRoute with LocalHistoryRoute