perf: add dart doc (LianjiaTech#483)

* perf: add dart doc * perf: add dart doc * fix: issue LianjiaTech#482
violinday · Aug 17, 2023 · 80261f3 · 80261f3
1 parent 37e21b8
commit 80261f3
Show file tree

Hide file tree

Showing 54 changed files with 354 additions and 99 deletions.
diff --git a/lib/src/components/appraise/brn_appraise.dart b/lib/src/components/appraise/brn_appraise.dart
@@ -225,7 +225,7 @@ class _BrnAppraiseState extends State<BrnAppraise> {
   Widget _confirmButton() {
     if (widget.config.showConfirmButton) {
       return Padding(
-        padding: EdgeInsets.symmetric(horizontal: 16),
+        padding: EdgeInsets.symmetric(vertical: 16),
         child: BrnBigMainButton(
           title: widget.config.confirmButtonText ?? BrnIntl.of(context).localizedResource.submit,
           isEnable: _enable ?? _appraiseIndex != -1,

diff --git a/lib/src/components/appraise/brn_flutter_gif_image.dart b/lib/src/components/appraise/brn_flutter_gif_image.dart
@@ -8,7 +8,6 @@ import 'package:flutter/widgets.dart';
 /// 参考来自github：https://github.com/peng8350/flutter_gifimage
 /// 感谢 Jpeng
 class GifImage extends StatefulWidget {
-  ///
   final VoidCallback? onFetchCompleted;
   final AnimationController controller;
   final ImageProvider image;

diff --git a/lib/src/components/charts/brn_progress_bar_chart/brn_progress_bar_chart.dart b/lib/src/components/charts/brn_progress_bar_chart/brn_progress_bar_chart.dart
@@ -4,7 +4,7 @@ import 'package:flutter/material.dart';
 /// BrnProgressBarChart
 /// 柱形数据图表
 /// 展示一组或者多组数据，方便数据的查看以及对比
-/// ignore: must_be_immutable
+// ignore: must_be_immutable
 class BrnProgressBarChart extends StatefulWidget {
   /// 图表最小宽度，默认0
   final double minWidth;

diff --git a/lib/src/components/charts/broken_line/brn_line_painter.dart b/lib/src/components/charts/broken_line/brn_line_painter.dart
@@ -7,6 +7,7 @@ import 'package:bruno/src/theme/brn_theme_configurator.dart';
 import 'package:flutter/material.dart';
 import 'package:path_drawing/path_drawing.dart';
 
+/// 折线图 刻度线、X/Y 轴绘制类
 class BrnLinePainter extends BrnBasePainter {
   final int lineSelectIndex;
   final int pointSelectIndex;
@@ -47,10 +48,13 @@ class BrnLinePainter extends BrnBasePainter {
   /// 绘制线条的参数内容
   List<BrnPointsLine> lines;
 
+  /// 是否展示 X、Y 轴刻度文本
   bool isShowXText, isShowYText;
 
+  /// 是否展示 X轴刻度
   final bool isShowXDial;
 
+  /// 是否展示选中点对应的 X、Y 辅助虚线
   final bool showPointDashLine;
 
   /// 默认的边距
@@ -111,10 +115,12 @@ class BrnLinePainter extends BrnBasePainter {
     assert(yDialMax > yDialMin, "yDialMax 应该大于 yDialMin");
   }
 
+  /// 返回选中的点
   Point selectedPoint(int lineIndex, int pointIndex) {
     return _linePointPositions[lineIndex][pointIndex];
   }
 
+  /// 根据点击的位置和 point 的 index，遍历寻找出所属的 Line
   int lineIndexCompute(Offset offset, int pointIndex) {
     int index = -1;
     double margin = 15;
@@ -540,7 +546,7 @@ class BrnLinePainter extends BrnBasePainter {
                     style: item.points[i].pointTextStyle),
                 textDirection: TextDirection.ltr)
               ..layout();
-            double adjustOffset = isAdjustPosition(lineIndex,
+            double adjustOffset = _isAdjustPosition(lineIndex,
                     _linePointPositions[lineIndex][i], _linePointPositions)
                 ? (20 - tpX.height)
                 : -20;
@@ -559,9 +565,10 @@ class BrnLinePainter extends BrnBasePainter {
     }
   }
 
-  bool isAdjustPosition(
+  /// 是否需要调整位置
+  bool _isAdjustPosition(
       int lineIndex, Point currentPoint, List<List<Point<num>>> lines) {
-    List<Point<num>> sameXPoints = getSameXValuePoints(currentPoint, lines);
+    List<Point<num>> sameXPoints = _getSameXValuePoints(currentPoint, lines);
     if (sameXPoints.isNotEmpty) {
       if (currentPoint.distanceTo(sameXPoints[0]) == 0) {
         return lineIndex > 0;
@@ -572,7 +579,8 @@ class BrnLinePainter extends BrnBasePainter {
     return false;
   }
 
-  List<Point<num>> getSameXValuePoints(
+  /// 获取相同x值的点
+  List<Point<num>> _getSameXValuePoints(
       Point currentPoint, List<List<Point<num>>> lines) {
     List<Point<num>> sameXPoints = [];
     for (int lineIndex = 0; lineIndex < lines.length; lineIndex++) {
@@ -588,7 +596,7 @@ class BrnLinePainter extends BrnBasePainter {
   }
 }
 
-//绘制图表的计算之后的结果模型集
+/// 绘制图表的计算之后的结果模型集
 class LineCanvasModel {
   final List<Path> paths;
   final Color pathColor;

diff --git a/lib/src/components/charts/broken_line/brn_line_y_painter.dart b/lib/src/components/charts/broken_line/brn_line_y_painter.dart
@@ -48,6 +48,7 @@ class BrnLineYPainter extends BrnBasePainter {
   /// 绘制线条的参数内容
   List<BrnPointsLine> lines;
 
+  /// 是否展示 X、Y 轴刻度文本
   bool isShowXDialText, isShowYDialText;
 
   double? selectX;

diff --git a/lib/src/components/dialog/brn_share_dialog.dart b/lib/src/components/dialog/brn_share_dialog.dart
@@ -27,7 +27,6 @@ typedef BrnShareDialogGetCustomShareItemIcon = Widget? Function(int index);
 /// 可自定义分享弹框标题文案
 /// 可自定义分享弹框辅助信息
 /// 可自定义文案和分享渠道中间的分割线内文案
-///
 // ignore: must_be_immutable
 class BrnShareDialog extends StatelessWidget {
   final BuildContext context;

diff --git a/lib/src/components/dialog/brn_single_select.dart b/lib/src/components/dialog/brn_single_select.dart
@@ -94,9 +94,7 @@ class BrnSingleSelectDialog extends Dialog {
   }
 }
 
-///
 /// 单选列表弹框 widget
-///
 // ignore: must_be_immutable
 class BrnSingleSelectDialogWidget extends StatefulWidget {
   final bool isClose;

diff --git a/lib/src/components/form/items/general/brn_radio_input_item.dart b/lib/src/components/form/items/general/brn_radio_input_item.dart
@@ -14,7 +14,6 @@ import 'package:flutter/material.dart';
 /// 包括"标题"、"副标题"、"错误信息提示"、"必填项提示"、"添加/删除按钮"、"消息提示"、
 /// "单选项"等元素
 ///
-
 // ignore: must_be_immutable
 class BrnRadioInputFormItem extends StatefulWidget {
   /// 录入项的唯一标识，主要用于录入类型页面框架中

diff --git a/lib/src/components/gallery/page/brn_gallery_detail_page.dart b/lib/src/components/gallery/page/brn_gallery_detail_page.dart
@@ -17,7 +17,7 @@ import 'package:flutter/material.dart';
 /// 组件提供了（列表页<-->详情页）这种交互模式的骨架，
 /// 适用于查看图片，视频 PDF 等场景。
 /// 默认只实现了图片的查看，如果想要扩展视频或者pdf自行扩展配置接口可实现。
-/// ignore: must_be_immutable
+// ignore: must_be_immutable
 class BrnGalleryDetailPage extends StatefulWidget {
   /// 该交互下所有 item 的配置集合
   final List<BrnBasicGroupConfig> allConfig;

diff --git a/lib/src/components/guide/brn_tip_widget.dart b/lib/src/components/guide/brn_tip_widget.dart
@@ -6,26 +6,46 @@ import 'package:bruno/src/theme/brn_theme_configurator.dart';
 import 'package:bruno/src/utils/brn_tools.dart';
 import 'package:flutter/material.dart';
 
+/// 引导组件试，[force] 有蒙层遮挡，[soft] 无蒙层遮挡
 enum GuideMode { force, soft }
 
 /// 默认的引导组件包含，强和弱两种交互模式
 class BrnTipInfoWidget extends StatelessWidget {
+
+  /// 引导组件的方向
   final GuideDirection direction;
+
+  /// 关闭按钮的回调
   final void Function()? onClose;
+
+  /// 下一步按钮的回调
   final void Function()? onNext;
+
+  /// 跳过按钮的回调
   final void Function()? onSkip;
 
+  /// 引导组件的宽度
   final double width;
+
+  /// 引导组件的高度
   final double? height;
+
+  /// 引导组件的内容
   final BrnTipInfoBean info;
+
+  /// 引导模式
   final GuideMode mode;
 
-  /// Which guide page is currently displayed, starting from 0
+  /// 当前的引导步数
   final int currentStepIndex;
 
-  /// Total number of guide pages
+  /// 引导步数
   final int stepCount;
+
+  /// 箭头距离指示的边距
   final double? arrowPadding;
+
+  /// 【下一步】的文案
   final String? nextTip;
 
   const BrnTipInfoWidget(

diff --git a/lib/src/components/noticebar/brn_marquee_text.dart b/lib/src/components/noticebar/brn_marquee_text.dart
@@ -22,9 +22,7 @@ class BrnMarqueeText extends StatefulWidget {
   final int timerRest;
 
   /// 尽量设置宽高，自动算宽|高受布局影响较大
-  double width;
-
-  double height;
+  double width, height;
 
   BrnMarqueeText({
     required this.text,

diff --git a/lib/src/components/picker/base/brn_picker_title.dart b/lib/src/components/picker/base/brn_picker_title.dart
@@ -7,7 +7,6 @@ import 'package:bruno/src/theme/brn_theme.dart';
 import 'package:flutter/material.dart';
 
 /// DatePicker's title widget.
-
 // ignore: must_be_immutable
 class BrnPickerTitle extends StatelessWidget {
   final BrnPickerTitleConfig pickerTitleConfig;

diff --git a/lib/src/components/picker/multi_range_picker/brn_multi_column_picker.dart b/lib/src/components/picker/multi_range_picker/brn_multi_column_picker.dart
@@ -29,7 +29,7 @@ typedef BrnOnPickerConfirm = void Function(Map<String, List<BrnPickerEntity>> re
 
 /// 从屏幕下方弹起的多级筛选选择器
 /// 可设置筛项的层级、多选、单选等筛选相关功能
-/// ignore: must_be_immutable
+// ignore: must_be_immutable
 class BrnMultiColumnPicker extends StatefulWidget {
   /// 筛选数据源
   final BrnPickerEntity entity;

diff --git a/lib/src/components/picker/multi_select_bottom_picker/brn_multi_select_data.dart b/lib/src/components/picker/multi_select_bottom_picker/brn_multi_select_data.dart
@@ -1,9 +1,13 @@
+/// 底部多选 Picker 数据类
 class BrnMultiSelectBottomPickerItem {
-  String code; //选项编号
+  /// 选项编号
+  String code;
 
-  String content; //选项内容
+  /// 选项内容
+  String content;
 
-  bool isChecked; //是否选中
+  /// 是否选中
+  bool isChecked;
 
   BrnMultiSelectBottomPickerItem(this.code, this.content,
       {this.isChecked = false});

diff --git a/lib/src/components/picker/time_picker/date_picker/brn_time_widget.dart b/lib/src/components/picker/time_picker/date_picker/brn_time_widget.dart
@@ -12,6 +12,7 @@ import 'package:flutter/material.dart';
 
 enum ColumnType { hour, minute, second }
 
+/// BrnTimeWidget widget. Can display time picker
 // ignore: must_be_immutable
 class BrnTimeWidget extends StatefulWidget {
   BrnTimeWidget({

diff --git a/lib/src/components/picker/time_picker/date_range_picker/brn_time_range_side_widget.dart b/lib/src/components/picker/time_picker/date_range_picker/brn_time_range_side_widget.dart
@@ -7,7 +7,6 @@ import 'package:bruno/src/theme/brn_theme.dart';
 import 'package:flutter/material.dart';
 
 /// TimeRangeSidePicker widget.
-
 // ignore: must_be_immutable
 class BrnTimeRangeSideWidget extends StatefulWidget {
   /// 可选最小时间

diff --git a/lib/src/components/popup/brn_measure_size.dart b/lib/src/components/popup/brn_measure_size.dart
@@ -4,7 +4,7 @@ import 'package:flutter/rendering.dart';
 
 typedef OnWidgetSizeChange = void Function(Size size);
 
-/// 描述: 计算 Widget 宽高的工具类。
+/// 监听 Widget 宽高的工具类。
 class MeasureSizeRenderObject extends RenderProxyBox {
   Size? oldSize;
   final OnWidgetSizeChange onChange;
@@ -29,6 +29,7 @@ class MeasureSizeRenderObject extends RenderProxyBox {
   }
 }
 
+/// 监听 Widget 宽高变化的工具类
 class MeasureSize extends SingleChildRenderObjectWidget {
   final OnWidgetSizeChange onChange;
 

diff --git a/lib/src/components/popup/brn_overlay_window.dart b/lib/src/components/popup/brn_overlay_window.dart
@@ -236,6 +236,7 @@ class _BrnOverlayWindowState extends State<BrnOverlayWindow> {
   }
 }
 
+/// [OverlayWindow] 组件展示隐藏控制器
 class BrnOverlayController {
   OverlayEntry? _entry;
 
@@ -246,13 +247,15 @@ class BrnOverlayController {
 
   BrnOverlayController._(this.context, this._entry);
 
+  /// 显示OverlayWindow
   showOverlay() {
     if (_entry != null) {
       Overlay.of(context).insert(_entry!);
       _isOverlayShowing = true;
     }
   }
 
+  /// 移除OverlayWindow
   void removeOverlay() {
     _entry?.remove();
     _entry = null;

diff --git a/lib/src/components/rating/brn_rating_star.dart b/lib/src/components/rating/brn_rating_star.dart
@@ -6,6 +6,7 @@ import 'package:flutter/material.dart';
 /// state，[RatingState] 星星状态
 typedef BrnRatingStarBuilder = Widget Function(RatingState state);
 
+/// 星星状态
 enum RatingState {
   /// 半颗
   half,

diff --git a/lib/src/components/scroll_anchor/brn_scroll_anchor_tab.dart b/lib/src/components/scroll_anchor/brn_scroll_anchor_tab.dart
@@ -10,14 +10,21 @@ typedef AnchorTabWidgetIndexedBuilder = Widget Function(BuildContext context, in
 /// 构建指定索引的Tab
 typedef AnchorTabIndexedBuilder = BadgeTab Function(BuildContext context, int index);
 
+/// 滑动锚点组件
 class BrnAnchorTab extends StatefulWidget {
-  // TabBar的样式
+  /// TabBar的样式
   final BrnAnchorTabBarStyle tabBarStyle;
+
+  /// 构建指定索引的Widget
   final AnchorTabWidgetIndexedBuilder? widgetIndexedBuilder;
+
+  /// 构建指定索引的Tab
   final AnchorTabIndexedBuilder tabIndexedBuilder;
+
+  /// Tab与内容之间的分割线
   final Widget? tabDivider;
 
-  //设置tab与widget的个数
+  /// 设置tab与widget的个数
   final int itemCount;
 
   BrnAnchorTab(
@@ -33,28 +40,28 @@ class BrnAnchorTab extends StatefulWidget {
 
 class _BrnScrollAnchorTabWidgetState extends State<BrnAnchorTab>
     with SingleTickerProviderStateMixin {
-  //用于控制 滑动
+  /// 用于控制 滑动
   late ScrollController _scrollController;
 
-  //用于控制tab
+  /// 用于控制tab
   late TabController _tabController;
 
-  //滑动组件的 key
+  /// 滑动组件的 key
   late GlobalKey _key;
 
-  //当前选中的索引
+  /// 当前选中的索引
   int currentIndex = 0;
 
-  //滑动组件的元素的key
+  /// 滑动组件的元素的key
   late List<GlobalKey> _bodyKeyList;
 
-  //每个元素在滑动组件中的位置
+  /// 每个元素在滑动组件中的位置
   late List<double> _cardOffsetList;
 
-  //是否点击滑动
+  /// 是否点击滑动
   bool tab = false;
 
-  //滑动组件在屏幕的位置
+  /// 滑动组件在屏幕的位置
   double listDy = 0;
 
   @override
@@ -207,7 +214,7 @@ class _BrnScrollAnchorTabWidgetState extends State<BrnAnchorTab>
     }
   }
 
-  //根据偏移量 确定tab索引
+  /// 根据偏移量 确定tab索引
   int createIndex(double offset) {
     int index = widget.itemCount - 1;
     for (int i = 0; i < widget.itemCount - 1; i++) {