From 0bebd2c05cd84ad94057a59c328ca9880091045a Mon Sep 17 00:00:00 2001 From: Harsh Bhikadia Date: Sat, 18 Dec 2021 17:58:29 +0530 Subject: [PATCH 1/2] docs: start doc-comments with a single sentence summary https://dart.dev/guides/language/effective-dart/documentation#do-start-doc-comments-with-a-single-sentence-summary --- lib/src/app_bar.dart | 12 ++++--- lib/src/button.dart | 5 +-- lib/src/navigation.dart | 2 +- lib/src/scaffold.dart | 72 ++++++++++++++++++++++++----------------- 4 files changed, 53 insertions(+), 38 deletions(-) diff --git a/lib/src/app_bar.dart b/lib/src/app_bar.dart index f44b8f9..6d7957d 100644 --- a/lib/src/app_bar.dart +++ b/lib/src/app_bar.dart @@ -1,12 +1,14 @@ import 'package:backdrop/backdrop.dart'; import 'package:flutter/material.dart'; -/// A material app bar that offers functionality for triggering the -/// [BackdropScaffold]'s functionality. It is internally implemented using the -/// [AppBar] class. +/// A material app bar with backdrop related functionality. /// -/// What differs from the [AppBar] implementation is the behaviour of -/// [BackdropAppBar.leading] and [BackdropAppBar.automaticallyImplyLeading]. +/// It offers functionality for triggering the [BackdropScaffold]'s +/// functionality. +/// +/// It is internally implemented using the [AppBar] class. What differs from +/// the [AppBar] implementation is the behaviour of [BackdropAppBar.leading] and +/// [BackdropAppBar.automaticallyImplyLeading]. /// /// Usage example: /// ```dart diff --git a/lib/src/button.dart b/lib/src/button.dart index 6fe16d5..474b011 100644 --- a/lib/src/button.dart +++ b/lib/src/button.dart @@ -1,8 +1,9 @@ import 'package:backdrop/backdrop.dart'; import 'package:flutter/material.dart'; -/// An animated button that can be used to trigger the backdrop functionality of -/// [BackdropScaffold]. +/// An animated button with backdrop related functionality. +/// +/// It can be used to trigger the backdrop functionality of [BackdropScaffold]. /// /// This button is implicitly used within [BackdropAppBar]. /// This button can also be passed to the [BackdropAppBar.actions]. diff --git a/lib/src/navigation.dart b/lib/src/navigation.dart index 44efeb5..bf6d8f5 100644 --- a/lib/src/navigation.dart +++ b/lib/src/navigation.dart @@ -3,7 +3,7 @@ import 'package:flutter/material.dart'; /// Implements the back layer to be used for navigation. /// -/// This class can be used as a back layer for [BackdropScaffold]. It enables to +/// This class can be used as [BackdropScaffold.backLayer]. It enables to /// use the back layer as a navigation list, similar to a [Drawer]. /// /// Usage example: diff --git a/lib/src/scaffold.dart b/lib/src/scaffold.dart index b946cfd..8f2c96d 100644 --- a/lib/src/scaffold.dart +++ b/lib/src/scaffold.dart @@ -3,11 +3,14 @@ import 'package:flutter/gestures.dart'; import 'package:flutter/material.dart'; import 'package:flutter/scheduler.dart'; -/// This class is an InheritedWidget that exposes state of [BackdropScaffold] -/// [BackdropScaffoldState] to be accessed from anywhere below the widget tree. +/// [InheritedWidget] that exposes state of [BackdropScaffold]. /// -/// It can be used to explicitly call backdrop functionality like fling, -/// concealBackLayer, revealBackLayer, etc. +/// [Backdrop.of] can be used to access [BackdropScaffoldState] from anywhere +/// below the widget tree. +/// +/// It can be used to explicitly call backdrop functionality like +/// [BackdropScaffoldState.fling], [BackdropScaffoldState.concealBackLayer], +/// [BackdropScaffoldState.revealBackLayer], etc. /// /// Example: /// ```dart @@ -75,22 +78,25 @@ class BackdropScaffold extends StatefulWidget { /// The widget shown at the top of the front layer. /// - /// When the front layer is minimized (back layer revealed), the entire [subHeader] will be visible unless - /// [headerHeight] is specified. + /// When the front layer is minimized (back layer revealed), the entire + /// [subHeader] will be visible unless [headerHeight] is specified. final Widget? subHeader; - /// If true, the scrim applied to the front layer while minimized (back layer revealed) will not - /// cover the [subHeader]. See [frontLayerScrim]. + /// Keeps [subHeader] active when minimized (back layer revealed). + /// + /// If true, the scrim applied to the front layer while minimized (back layer + /// revealed) will not cover the [subHeader]. See [frontLayerScrim]. /// /// Defaults to true. final bool subHeaderAlwaysActive; - /// Defines the front layer's height when minimized (back layer revealed)). + /// Defines the front layer's height when minimized (back layer revealed). + /// /// Defaults to measured height of [subHeader] if provided, else 32. /// - /// To automatically use the difference of the screen height and back layer's height, - /// see [stickyFrontLayer]. Note [headerHeight] is ignored if it is less - /// than the available size and [stickyFrontLayer] is `true`. + /// To automatically use the difference of the screen height and back layer's + /// height, see [stickyFrontLayer]. Note [headerHeight] is ignored if it is + /// less than the available size and [stickyFrontLayer] is `true`. /// /// To vary the front layer's height when active (back layer concealed), /// see [frontLayerActiveFactor]. @@ -107,18 +113,19 @@ class BackdropScaffold extends StatefulWidget { /// ``` final BorderRadius frontLayerBorderRadius; - /// Indicates the front layer should minimize to the back layer's - /// bottom edge. Otherwise, see [headerHeight] to specify this value. + /// Indicates the front layer should minimize to the back layer's bottom edge. + /// + /// Otherwise, see [headerHeight] to specify this value. /// Defaults to `false`. /// /// This parameter has no effect if the back layer's measured height /// is greater than or equal to the screen height. final bool stickyFrontLayer; - /// Flag indicating whether the back layer should be revealed at the beginning - /// or not. Setting [revealBackLayerAtStart] to `true` reveals the back layer - /// at start. This property has no effect if a custom [animationController] - /// is set. + /// Indicates whether the back layer should be revealed at the beginning. + /// + /// Setting it to `true` reveals the back layer at start. This property has + /// no effect if a custom [animationController] is set. /// /// Defaults to `false`. final bool revealBackLayerAtStart; @@ -143,8 +150,9 @@ class BackdropScaffold extends StatefulWidget { /// If null, the color is handled automatically according to the theme. final Color? frontLayerBackgroundColor; - /// Fraction of the available height the front layer will occupy, - /// when active (back layer concealed). Clamped to (0, 1). + /// Fraction of available height the [frontLayer] will occupy when active (back layer concealed). + /// + /// The value is clamped to (0, 1). /// /// Note the front layer will not fully conceal the back layer when /// this value is less than 1. A scrim will cover the @@ -153,14 +161,17 @@ class BackdropScaffold extends StatefulWidget { /// Defaults to 1. final double frontLayerActiveFactor; - /// Defines the scrim color for the front layer when minimized - /// (revealing the back layer) and animating. Defaults to [Colors.white70]. + /// Scrim over [frontLayer] when minimized (back layer revealed) and animating. + /// + /// Defaults to [Colors.white70]. /// /// See [subHeaderAlwaysActive] to leave the [subHeader] outside the scrim. final Color frontLayerScrim; - /// Defines the scrim color for the back layer when partially concealed - /// (with [frontLayerActiveFactor] less than 1). + /// Scrim over [backLayer] when active (back layer concealed). + /// + /// It is only visible when [backLayer] is concealed partially, ie. when + /// [frontLayerActiveFactor] is less than 1. /// /// Defaults to [Colors.black54]. final Color backLayerScrim; @@ -171,12 +182,11 @@ class BackdropScaffold extends StatefulWidget { /// Will be called when [backLayer] has been revealed. final VoidCallback? onBackLayerRevealed; - /// Specifies whether the state of the [backLayer] is maintained when it is - /// revealed and concealed. + /// Specifies whether the state of the [backLayer] should be maintained. /// /// When true, the [backLayer] is kept in the tree while concealed. /// When false, the [backLayer] is removed from the tree when concealed and - /// recreated when revealed. + /// recreated when revealed. [backLayer] is built everytime it is revealed. /// /// Defaults to `true`. final bool maintainBackLayerState; @@ -324,8 +334,9 @@ class BackdropScaffoldState extends State late AnimationController _animationController; late ColorTween _backLayerScrimColorTween; - /// Key for accessing the [ScaffoldState] of [BackdropScaffold]'s internally - /// used [Scaffold]. + /// Key for accessing the underlying [ScaffoldState]. + /// + /// It exposes state of [Scaffold] used internally by [BackdropScaffold]. GlobalKey? scaffoldKey; double _backPanelHeight = 0; double _subHeaderHeight = 0; @@ -617,7 +628,8 @@ class BackdropScaffoldState extends State } } -/// Widget to get size of child widget +/// Widget to get size of child widget. +/// /// Credit: https://stackoverflow.com/a/60868972/2554745 class _MeasureSize extends StatefulWidget { final Widget child; From 710ead8a96b5f92d1759c18e2679ab8605f35fcc Mon Sep 17 00:00:00 2001 From: Harsh Bhikadia Date: Sun, 19 Dec 2021 13:21:44 +0530 Subject: [PATCH 2/2] minor --- lib/src/scaffold.dart | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/lib/src/scaffold.dart b/lib/src/scaffold.dart index 8f2c96d..8596e48 100644 --- a/lib/src/scaffold.dart +++ b/lib/src/scaffold.dart @@ -150,12 +150,13 @@ class BackdropScaffold extends StatefulWidget { /// If null, the color is handled automatically according to the theme. final Color? frontLayerBackgroundColor; - /// Fraction of available height the [frontLayer] will occupy when active (back layer concealed). + /// Fraction of available height the [frontLayer] will occupy when active + /// (back layer concealed). /// /// The value is clamped to (0, 1). /// /// Note the front layer will not fully conceal the back layer when - /// this value is less than 1. A scrim will cover the + /// this value is less than 1. A scrim will cover the /// partially concealed back layer; see [backLayerScrim]. /// /// Defaults to 1.