Add Documentation

Author: rayliverified

lib/responsive_row_column.dart

@@ -1,6 +1,22 @@
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/widgets.dart';
 
+/// A convenience wrapper for responsive [Row] and
+/// [Column] switching with padding and spacing.
+///
+/// ResponsiveRowColumn combines responsiveness
+/// behaviors for managing rows and columns into one
+/// convenience widget. This widget requires all [children]
+/// to be [ResponsiveRowColumnItem] widgets.
+/// Row vs column layout is controlled by [rowColumn].
+/// RowColumn is Row layout when true and Column
+/// layout when false.
+/// Add spacing between widgets with [rowSpacing] and
+/// [columnSpacing]. Add padding around widgets with
+/// [rowPadding] and [columnPadding].
+///
+/// See [ResponsiveRowColumnItem] for [Flex] and
+/// [FlexFit] options.
 class ResponsiveRowColumn extends StatelessWidget {
   final List<ResponsiveRowColumnItem> children;
   final bool rowColumn;
@@ -20,7 +36,6 @@ class ResponsiveRowColumn extends StatelessWidget {
   final double columnSpacing;
   final EdgeInsets rowPadding;
   final EdgeInsets columnPadding;
-  final bool fillRow;
   get isRow => rowColumn;
   get isColumn => !rowColumn;
 
@@ -42,7 +57,6 @@ class ResponsiveRowColumn extends StatelessWidget {
       this.columnTextBaseline,
       this.rowSpacing,
       this.columnSpacing,
-      this.fillRow = false,
       this.rowPadding = EdgeInsets.zero,
       this.columnPadding = EdgeInsets.zero})
       : super(key: key);
@@ -80,6 +94,7 @@ class ResponsiveRowColumn extends StatelessWidget {
           );
   }
 
+  /// Logic to construct widget [children].
   List<Widget> buildChildren(
       List<ResponsiveRowColumnItem> children, bool rowColumn, double spacing) {
     // Sort ResponsiveRowColumnItems by their order.
@@ -91,7 +106,7 @@ class ResponsiveRowColumn extends StatelessWidget {
         return a.columnOrder.compareTo(b.columnOrder);
       }
     });
-    // Add padding between items.
+    // Add padding between widgets..
     List<Widget> widgetList = [];
     for (int i = 0; i < childrenHolder.length; i++) {
       widgetList.add(childrenHolder[i].copyWith(rowColumn: rowColumn));
@@ -105,6 +120,16 @@ class ResponsiveRowColumn extends StatelessWidget {
   }
 }
 
+/// A wrapper for [ResponsiveRowColumn] children with
+/// responsiveness.
+///
+/// Control the order of widgets within [ResponsiveRowColumn]
+/// by assigning a [rowOrder] or [columnOrder] value.
+/// Widgets without an order value are ranked behind
+/// those with order values.
+/// Set a widget's [Flex] value through [rowFlex] and
+/// [columnFlex]. Set a widget's [FlexFit] through
+/// [rowFit] and [columnFit].
 class ResponsiveRowColumnItem extends StatelessWidget {
   final Widget child;
   final int rowOrder;
@@ -129,9 +154,9 @@ class ResponsiveRowColumnItem extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    if (rowColumn && rowFlex != null) {
+    if (rowColumn && (rowFlex != null || rowFit != null)) {
       return Flexible(flex: rowFlex, fit: rowFit, child: child);
-    } else if (!rowColumn && columnFlex != null) {
+    } else if (!rowColumn && (columnFlex != null || columnFit != null)) {
       return Flexible(flex: columnFlex, fit: columnFit, child: child);
     }
 

lib/responsive_value.dart

@@ -2,9 +2,16 @@ import 'package:flutter/widgets.dart';
 
 import 'responsive_framework.dart';
 
-typedef T Value<T>();
-typedef StartListening<T> = VoidCallback Function(Value<T> element, T value);
-
+/// Conditional values based on the active breakpoint.
+///
+/// Get a [value] that corresponds to active breakpoint
+/// determined by [Condition]s set in [valueWhen].
+/// Set a [defaultValue] for when no condition is
+/// active. Requires a parent [context] that contains
+/// a [ResponsiveWrapper].
+///
+/// No validation is performed on [Condition]s so
+/// valid conditions must be passed.
 class ResponsiveValue<T> {
   T value;
   final T defaultValue;
@@ -119,12 +126,18 @@ class ResponsiveValue<T> {
   }
 }
 
+/// Internal equality comparators.
 enum Conditional {
   LARGER_THAN,
   EQUALS,
   SMALLER_THAN,
 }
 
+/// A conditional value provider.
+///
+/// Provides the [value] when the [condition] is active.
+/// Compare conditions by setting either [breakpoint] or
+/// [name] values.
 class Condition<T> {
   final int breakpoint;
   final String name;
@@ -186,6 +199,11 @@ class Condition<T> {
   }
 }
 
+/// A convenience wrapper for responsive [Visibility].
+///
+/// ResponsiveVisibility accepts [Condition]s in
+/// [visibleWhen] and [hiddenWhen] convenience
+/// fields. The [child] widget is [visible] by default.
 class ResponsiveVisibility extends StatelessWidget {
   final Widget child;
   final bool visible;

lib/responsive_wrapper.dart

@@ -398,6 +398,8 @@ class _ResponsiveWrapperState extends State<ResponsiveWrapper>
         devicePixelRatio: devicePixelRatio * activeScaleFactor);
   }
 
+  /// Calculate breakpoint segments algorithm. Performs
+  /// a single pass
   List<ResponsiveBreakpointSegment> getBreakpointSegments(
       List<ResponsiveBreakpoint> breakpoints,
       ResponsiveBreakpoint defaultBreakpoint) {
@@ -414,10 +416,14 @@ class _ResponsiveWrapperState extends State<ResponsiveWrapper>
     // Perform ordering operation to allow breakpoints
     // to be accepted in any order.
     breakpoints.sort((a, b) {
-      // If breakpoints are equal, return autoScaleDown
-      // breakpoints first.
+      // If breakpoints are equal, return in the following order:
+      // AutoScaleDown, Resize, AutoScale.
       if (a.breakpoint == b.breakpoint && a.isAutoScaleDown) {
-        if (a.isAutoScaleDown) {
+        if (a.isAutoScaleDown && !b.isAutoScaleDown) {
+          return -1;
+        }
+
+        if (a.isResize && !b.isAutoScaleDown) {
           return -1;
         }
 
@@ -765,6 +771,20 @@ enum _ResponsiveBreakpointBehavior {
   TAG,
 }
 
+/// Control the responsiveness of the app at a breakpoint.
+///
+/// Specify a responsive [behavior] at a [breakpoint]
+/// value. The following behaviors are supported:
+/// Resize - default behavior.
+/// AutoScale - scales UI from breakpoint up.
+/// AutoScaleDown - scales UI from breakpoint down and
+/// from breakpoint up. Has the same behavior as AutoScale
+/// but scales down as well.
+/// Tag - named breakpoint value. Inherits behavior.
+/// Add a [name] to a breakpoint for ease of reference.
+/// The [scaleFactor] enlarges or shrinks the UI by a
+/// multiple of x. This values can be applied to all
+/// breakpoints.
 @immutable
 class ResponsiveBreakpoint {
   final double breakpoint;
@@ -839,6 +859,16 @@ class ResponsiveBreakpoint {
       ')';
 }
 
+/// Computed breakpoint segments.
+///
+/// Breakpoint segments are computed from
+/// 0 to infinity. The [breakpoint] specifies the
+/// start position for the [responsiveBreakpointBehavior].
+/// The [responsiveBreakpointBehavior] specifies
+/// how the segment behavior is computed.
+/// The [responsiveBreakpoint] holds the active
+/// breakpoint and controls the segment behavior.
+@immutable
 class ResponsiveBreakpointSegment {
   final double breakpoint;
   final _ResponsiveBreakpointBehavior responsiveBreakpointBehavior;