Merge pull request #1 from KevinZhang19870314/dev

Add dart doc comments

CHANGELOG.md

@@ -1,8 +1,12 @@
-## [0.1.1] - 2021-July-7.
+## [0.1.2] - 2021-July-6.
+
+* Add the dart doc comments.
+
+## [0.1.1] - 2021-July-5.
 
 * Revise readme.
 
-## [0.1.0] - 2021-July-7.
+## [0.1.0] - 2021-July-5.
 
 * Initial release
 * Support widgets for wired button, wired card, wired checkbox, wired combo, wired dialog, wired divider, wired input, wired radio, wired slider.

example/pubspec.lock

@@ -155,7 +155,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.1.1"
+    version: "0.1.2"
 sdks:
   dart: ">=2.12.0 <3.0.0"
   flutter: ">=1.17.0"

lib/rough/src/decoration.dart

@@ -2,7 +2,7 @@ import 'dart:math';
 import 'dart:ui';
 
 import 'package:flutter/material.dart';
-import './rough.dart';
+import 'rough.dart';
 
 import 'config.dart';
 import 'entities.dart';

lib/src/canvas/wired_canvas.dart

@@ -1,5 +1,5 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/rough/rough.dart';
+import '../../rough/rough.dart';
 
 import 'wired_painter_base.dart';
 import 'wired_painter.dart';

lib/src/canvas/wired_painter.dart

@@ -1,6 +1,6 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/rough/rough.dart';
-import 'package:wired_elements/src/canvas/wired_painter_base.dart';
+import '../../rough/rough.dart';
+import 'wired_painter_base.dart';
 
 class WiredPainter extends CustomPainter {
   final DrawConfig drawConfig;

lib/src/canvas/wired_painter_base.dart

@@ -1,6 +1,6 @@
 import 'dart:ui';
 
-import 'package:wired_elements/rough/rough.dart';
+import '../../rough/rough.dart';
 
 abstract class WiredPainterBase {
   void paintRough(

lib/src/wired_base.dart

@@ -1,23 +1,28 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/rough/rough.dart';
-import 'package:wired_elements/src/const.dart';
+import '../rough/rough.dart';
+import 'const.dart';
 
 import 'canvas/wired_painter_base.dart';
+import 'wired_button.dart';
 
+/// The utils for all wired widgets
 class WiredBase {
+  /// Default path painter for canvas
   static final Paint pathPaint = Paint()
     ..color = borderColor
     ..style = PaintingStyle.stroke
     ..isAntiAlias = true
     ..strokeCap = StrokeCap.square
     ..strokeWidth = 1;
 
+  /// Default fill painter for canvas
   static final Paint fillPaint = Paint()
     ..color = filledColor
     ..style = PaintingStyle.stroke
     ..isAntiAlias = true
     ..strokeWidth = 1;
 
+  /// The fill painter for canvas with [color]
   static Paint fillPainter(Color color) {
     return Paint()
       ..color = color
@@ -26,6 +31,7 @@ class WiredBase {
       ..strokeWidth = 1;
   }
 
+  /// The path painter for canvas with [strokeWidth]
   static Paint pathPainter(double strokeWidth) {
     return Paint()
       ..color = borderColor
@@ -35,9 +41,15 @@ class WiredBase {
   }
 }
 
+/// The wired base widget usually being extends by specific wired widgets like
+/// [WiredButton] for the purpose of isolates repaints.
+///
+/// If not do this, all the wired widgets (use rough decoration like [RoughBoxDecoration])
+/// in current screen will repaints together, which is not make sence.
 abstract class WiredBaseWidget extends StatelessWidget {
   const WiredBaseWidget({Key? key}) : super(key: key);
 
+  /// Wrap with [RepaintBoundary] to isolates repaints.
   @override
   Widget build(BuildContext context) {
     return RepaintBoundary(
@@ -46,9 +58,13 @@ abstract class WiredBaseWidget extends StatelessWidget {
     );
   }
 
+  /// The method for extended widget to implement to build widgets.
   Widget buildWiredElement();
 }
 
+/// The mixin for isolates repaints.
+///
+/// See [WiredBaseWidget] for same purpose.
 abstract class WiredRepaintMixin {
   Widget buildWiredElement({Key? key, required Widget child}) {
     return RepaintBoundary(
@@ -58,8 +74,12 @@ abstract class WiredRepaintMixin {
   }
 }
 
+/// Base wired rectangle.
 class WiredRectangleBase extends WiredPainterBase {
+  /// The amount of empty space to the leading edge of the rectangle.
   final double leftIndent;
+
+  /// The amount of empty space to the trailing edge of the rectangle.
   final double rightIndent;
 
   WiredRectangleBase({this.leftIndent = 0.0, this.rightIndent = 0.0});
@@ -79,6 +99,7 @@ class WiredRectangleBase extends WiredPainterBase {
   }
 }
 
+/// Base wired inverted triangle.
 class WiredInvertedTriangleBase extends WiredPainterBase {
   @override
   void paintRough(
@@ -96,6 +117,9 @@ class WiredInvertedTriangleBase extends WiredPainterBase {
   }
 }
 
+/// Base wired line with start point [x1], [y1] and end point [x2], [y2] using [strokeWidth].
+///
+/// [strokeWidth] defaults to 1.
 class WiredLineBase extends WiredPainterBase {
   final double x1, y1;
   final double x2, y2;
@@ -132,6 +156,9 @@ class WiredLineBase extends WiredPainterBase {
   }
 }
 
+/// Base wired circle with [diameterRatio] and [fillColor].
+///
+/// If [diameterRatio] = 1, then the diameter of circle is the canvas's width.
 class WiredCircleBase extends WiredPainterBase {
   final double diameterRatio;
   final Color fillColor;

lib/src/wired_button.dart

@@ -1,11 +1,25 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/rough/rough.dart';
+import '../rough/rough.dart';
 
 import 'const.dart';
 import 'wired_base.dart';
 
+/// Wired button.
+///
+/// Usage:
+/// ```dart
+/// WiredButton(
+///  child: WiredText('Wired Button'),
+///  onPressed: () {
+///   print('Wired Button');
+///  },
+/// ),
+/// ```
 class WiredButton extends WiredBaseWidget {
+  /// Typically the button's label.
   final Widget child;
+
+  /// Called when the button is tapped
   final void Function() onPressed;
 
   const WiredButton({

lib/src/wired_card.dart

@@ -1,10 +1,50 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/src/canvas/wired_canvas.dart';
-import 'package:wired_elements/src/wired_base.dart';
+import 'canvas/wired_canvas.dart';
+import 'wired_base.dart';
 
+/// Wired card.
+///
+/// Usage:
+/// ```dart
+/// WiredCard(
+///   height: 150.0,
+///   fill: false,
+///   child: Column(
+/// 	mainAxisSize: MainAxisSize.min,
+/// 	children: <Widget>[
+/// 	  const ListTile(
+/// 		leading: Icon(Icons.album),
+/// 		title: WiredText('The Enchanted Nightingale'),
+/// 		subtitle: WiredText(
+/// 			'Music by Julie Gable. Lyrics by Sidney Stein.'),
+/// 	  ),
+/// 	  Row(
+/// 		mainAxisAlignment: MainAxisAlignment.end,
+/// 		children: <Widget>[
+/// 		  WiredButton(
+/// 			child: const WiredText('BUY TICKETS'),
+/// 			onPressed: () {/* ... */},
+/// 		  ),
+/// 		  const SizedBox(width: 8),
+/// 		  WiredButton(
+/// 			child: const WiredText('LISTEN'),
+/// 			onPressed: () {/* ... */},
+/// 		  ),
+/// 		  const SizedBox(width: 8),
+/// 		],
+/// 	  ),
+/// 	],
+///   ),
+/// ),
+/// ```
 class WiredCard extends StatelessWidget {
+  /// The [child] contained by the card.
   final Widget? child;
+
+  /// [true] to fill by canvas fill painter, otherwise not.
   final bool fill;
+
+  /// The [height] of this card.
   final double? height;
 
   const WiredCard({

lib/src/wired_checkbox.dart

@@ -1,12 +1,27 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/rough/rough.dart';
+import '../rough/rough.dart';
 
 import 'const.dart';
 import 'wired_base.dart';
 
+/// Wired checkbox.
+///
+/// Usage:
+/// ```dart
+/// WiredCheckbox(
+///   value: false,
+///   onChanged: (value) {
+/// 	print('Wired Checkbox $value');
+///   },
+/// ),
+/// ```
 class WiredCheckbox extends StatefulWidget {
+  /// Determines the checkbox checked or not.
   final bool? value;
+
+  /// Called once the checkbox check status changes.
   final void Function(bool?) onChanged;
+
   const WiredCheckbox({
     Key? key,
     required this.value,

lib/src/wired_combo.dart

@@ -1,12 +1,38 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/rough/rough.dart';
-import 'package:wired_elements/src/wired_base.dart';
+import '../rough/rough.dart';
+import 'wired_base.dart';
 
 import 'canvas/wired_canvas.dart';
 
+/// Wired combo
+///
+/// Usage:
+/// ```dart
+/// WiredCombo(
+///   value: 'One',
+///   items: ['One', 'Two', 'Free', 'Four']
+/// 	  .map<DropdownMenuItem<String>>((dynamic value) {
+/// 	return DropdownMenuItem<String>(
+/// 	  value: value,
+/// 	  child: Padding(
+/// 		padding: EdgeInsets.only(left: 5.0),
+/// 		child: WiredText(value),
+/// 	  ),
+/// 	);
+///   }).toList(),
+///   onChanged: (value) {
+/// 	print('$value');
+///   },
+/// ),
+/// ```
 class WiredCombo extends StatefulWidget {
+  /// The selected value for combo.
   final dynamic value;
+
+  /// The selection items for combo.
   final List<DropdownMenuItem<dynamic>> items;
+
+  /// Called when the combo selected value changed.
   final Function(dynamic)? onChanged;
 
   const WiredCombo({

lib/src/wired_dialog.dart

@@ -1,10 +1,61 @@
 import 'package:flutter/material.dart';
-import 'package:wired_elements/src/wired_base.dart';
+import 'wired_base.dart';
 
 import 'canvas/wired_canvas.dart';
 
+/// Wired dialog.
+///
+/// Usage:
+/// ```dart
+/// WiredButton(
+/// 	onPressed: () {
+/// 	  showDialog(
+/// 		context: context,
+/// 		builder: (context) {
+/// 		  return Center(
+/// 			child: Container(
+/// 			  height: 480.0,
+/// 			  child: WiredDialog(
+/// 				child: Column(
+/// 				  crossAxisAlignment: CrossAxisAlignment.start,
+/// 				  children: [
+/// 					WiredText(
+/// 					  'Title',
+/// 					  fontSize: 20.0,
+/// 					  fontWeight: FontWeight.bold,
+/// 					),
+/// 					SizedBox(height: 15.0),
+/// 					WiredText(
+/// 					  'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.',
+/// 					),
+/// 					SizedBox(height: 15.0),
+/// 					Row(
+/// 					  mainAxisAlignment: MainAxisAlignment.end,
+/// 					  children: [
+/// 						WiredButton(
+/// 						  child: Text('OK'),
+/// 						  onPressed: () {
+/// 							Navigator.of(context).pop();
+/// 						  },
+/// 						),
+/// 					  ],
+/// 					),
+/// 				  ],
+/// 				),
+/// 			  ),
+/// 			),
+/// 		  );
+/// 		},
+/// 	  );
+/// 	},
+/// 	child: WiredText('Open wired dialog'),
+///   ),
+/// ```
 class WiredDialog extends StatelessWidget {
+  /// The content in dialog.
   final Widget child;
+
+  /// The padding for dialog's content, defaults to 20.0 if null.
   final EdgeInsetsGeometry? padding;
 
   const WiredDialog({