chore: add documentation

frontend/app_flowy/packages/flowy_board/lib/src/widgets/board_column/board_column.dart

@@ -1,7 +1,6 @@
 import 'package:flutter/material.dart';
 
 import '../../rendering/board_overlay.dart';
-import '../../utils/log.dart';
 import '../phantom/phantom_controller.dart';
 import '../flex/reorder_flex.dart';
 import '../flex/drag_target_inteceptor.dart';
@@ -110,7 +109,7 @@ class _BoardColumnWidgetState extends State<BoardColumnWidget> {
           onDragEnded: () {
             widget.phantomController.columnEndDragging(widget.columnId);
             widget.onDragEnded?.call(widget.columnId);
-            _printItems(widget.dataController);
+            widget.dataController.debugPrintItems();
           },
           dataSource: widget.dataController,
           interceptor: interceptor,
@@ -151,12 +150,3 @@ class _BoardColumnWidgetState extends State<BoardColumnWidget> {
     }
   }
 }
-
-void _printItems(BoardColumnDataController dataController) {
-  String msg = 'Column${dataController.columnData} data: ';
-  for (var element in dataController.items) {
-    msg = '$msg$element,';
-  }
-
-  Log.debug(msg);
-}

frontend/app_flowy/packages/flowy_board/lib/src/widgets/board_column/data_controller.dart

@@ -37,7 +37,8 @@ class BoardColumnData extends ReoderFlexItem with EquatableMixin {
   }
 }
 
-class BoardColumnDataController extends ChangeNotifier with EquatableMixin, ReoderFlextDataSource {
+class BoardColumnDataController extends ChangeNotifier
+    with EquatableMixin, ReoderFlextDataSource {
   final BoardColumnData columnData;
 
   BoardColumnDataController({
@@ -60,14 +61,16 @@ class BoardColumnDataController extends ChangeNotifier with EquatableMixin, Reod
     if (fromIndex == toIndex) {
       return;
     }
-    Log.debug('[$BoardColumnDataController] $columnData move item from $fromIndex to $toIndex');
+    Log.debug(
+        '[$BoardColumnDataController] $columnData move item from $fromIndex to $toIndex');
     final item = columnData._items.removeAt(fromIndex);
     columnData._items.insert(toIndex, item);
     notifyListeners();
   }
 
   void insert(int index, ColumnItem item, {bool notify = true}) {
-    Log.debug('[$BoardColumnDataController] $columnData insert $item at $index');
+    Log.debug(
+        '[$BoardColumnDataController] $columnData insert $item at $index');
     columnData._items.insert(index, item);
     if (notify) {
       notifyListeners();
@@ -77,10 +80,20 @@ class BoardColumnDataController extends ChangeNotifier with EquatableMixin, Reod
   void replace(int index, ColumnItem item) {
     final removedItem = columnData._items.removeAt(index);
     columnData._items.insert(index, item);
-    Log.debug('[$BoardColumnDataController] $columnData replace $removedItem with $item at $index');
+    Log.debug(
+        '[$BoardColumnDataController] $columnData replace $removedItem with $item at $index');
     notifyListeners();
   }
 
+  void debugPrintItems() {
+    String msg = '[$BoardColumnDataController] $columnData data: ';
+    for (var element in items) {
+      msg = '$msg$element,';
+    }
+
+    Log.debug(msg);
+  }
+
   @override
   List<ColumnItem> get items => UnmodifiableListView(columnData._items);
 

frontend/app_flowy/packages/flowy_board/lib/src/widgets/flex/drag_state.dart

@@ -4,18 +4,23 @@ import '../../utils/log.dart';
 import 'drag_target.dart';
 import 'reorder_flex.dart';
 
-/// [FlexDragTargetData] is used to store the custom dragging data. It can be used to
-/// locate the index of the dragging widget in the [BoardList].
+/// [FlexDragTargetData] is used to store the custom dragging data.
+///
+/// * [draggingIndex] the index of the dragTarget that is being dragged.
+/// * [draggingWidget] the widget of the dragTarget that is being dragged.
+/// * [reorderFlexId] the id of the [ReorderFlex]
+/// * [reorderFlexItem] the item of the [ReorderFlex]
+///
 class FlexDragTargetData extends DragTargetData {
   /// The index of the dragging target in the boardList.
   @override
   final int draggingIndex;
 
-  final DraggingState state;
+  final DraggingState _state;
 
-  Widget? get draggingWidget => state.draggingWidget;
+  Widget? get draggingWidget => _state.draggingWidget;
 
-  Size? get feedbackSize => state.feedbackSize;
+  Size? get feedbackSize => _state.feedbackSize;
 
   final String dragTargetId;
 
@@ -28,8 +33,8 @@ class FlexDragTargetData extends DragTargetData {
     required this.draggingIndex,
     required this.reorderFlexId,
     required this.reorderFlexItem,
-    required this.state,
-  });
+    required DraggingState state,
+  }) : _state = state;
 
   @override
   String toString() {

frontend/app_flowy/packages/flowy_board/lib/src/widgets/flex/drag_target.dart

@@ -13,9 +13,14 @@ abstract class ReorderFlexDraggableTargetBuilder {
       DragTargetWillAccpet<T> onWillAccept);
 }
 
+///
 typedef DragTargetWillAccpet<T extends DragTargetData> = bool Function(
     T dragTargetData);
+
+///
 typedef DragTargetOnStarted = void Function(Widget, int, Size?);
+
+///
 typedef DragTargetOnEnded<T extends DragTargetData> = void Function(
     T dragTargetData);
 

frontend/app_flowy/packages/flowy_board/lib/src/widgets/flex/drag_target_inteceptor.dart

@@ -50,7 +50,9 @@ class OverlapReorderFlexDragTargetInteceptor
       required String dragTargetId,
       required int dragTargetIndex}) {
     if (dragTargetId == dragTargetData.reorderFlexId) {
-      // Log.debug('remove all phantom');
+      Log.debug('remove all phantom');
+    } else {
+      Log.debug('add phantom to $dragTargetId');
     }
 
     return true;
@@ -58,6 +60,7 @@ class OverlapReorderFlexDragTargetInteceptor
 }
 
 abstract class CrossReorderFlexDragTargetDelegate {
+  /// * [reorderFlexId] is the id that the [ReorderFlex] passed in.
   bool acceptNewDragTargetData(
     String reorderFlexId,
     FlexDragTargetData dragTargetData,
@@ -66,7 +69,6 @@ abstract class CrossReorderFlexDragTargetDelegate {
 
   void updateDragTargetData(
     String reorderFlexId,
-    FlexDragTargetData dragTargetData,
     int dragTargetIndex,
   );
 }
@@ -129,16 +131,8 @@ class CrossReorderFlexDragTargetInterceptor
     );
 
     if (isNewDragTarget == false) {
-      delegate.updateDragTargetData(
-        reorderFlexId,
-        dragTargetData,
-        dragTargetIndex,
-      );
-
-      reorderFlexState.handleOnWillAccept(
-        context,
-        dragTargetIndex,
-      );
+      delegate.updateDragTargetData(reorderFlexId, dragTargetIndex);
+      reorderFlexState.handleOnWillAccept(context, dragTargetIndex);
     }
 
     return true;

frontend/app_flowy/packages/flowy_board/lib/src/widgets/phantom/phantom_controller.dart

@@ -20,7 +20,7 @@ class BoardPhantomController extends OverlapReorderFlexDragTargetDelegate
 
   PhantomRecord? phantomRecord;
 
-  final columnsState = ColumnPassthroughStateController();
+  final columnsState = ColumnPhantomStateController();
 
   BoardPhantomController({required this.delegate});
 
@@ -79,9 +79,11 @@ class BoardPhantomController extends OverlapReorderFlexDragTargetDelegate
     phantomRecord = null;
   }
 
+  /// Update the column's phantom index if it exists.
+  /// [toColumnId] the id of the column
+  /// [dragTargetIndex] the index of the dragTarget
   void _updatePhantom(
     String toColumnId,
-    FlexDragTargetData dragTargetData,
     int dragTargetIndex,
   ) {
     final columnDataController = delegate.controller(toColumnId);
@@ -99,6 +101,7 @@ class BoardPhantomController extends OverlapReorderFlexDragTargetDelegate
     }
   }
 
+  /// Remove the phantom in the column if it contains phantom
   void _removePhantom(String columnId) {
     final index = delegate
         .controller(columnId)
@@ -118,45 +121,51 @@ class BoardPhantomController extends OverlapReorderFlexDragTargetDelegate
     }
   }
 
+  /// Insert the phantom into column
+  ///
+  /// * [toColumnId] id of the column
+  /// * [phantomIndex] the phantom occupies index
   void _insertPhantom(
     String toColumnId,
     FlexDragTargetData dragTargetData,
     int phantomIndex,
   ) {
-    final items = delegate.controller(toColumnId)?.items;
-    if (items == null) {
-      return;
-    }
-
     final phantomContext = PassthroughPhantomContext(
       index: phantomIndex,
       dragTargetData: dragTargetData,
     );
     columnsState.addColumnListener(toColumnId, phantomContext);
-    Log.debug('$phantomContext');
     delegate
         .controller(toColumnId)
         ?.insert(phantomIndex, PhantomColumnItem(phantomContext));
 
     WidgetsBinding.instance.addPostFrameCallback((_) {
       Future.delayed(const Duration(milliseconds: 100), () {
+        Log.debug(
+            '[$BoardPhantomController] notify $toColumnId to insert phantom');
         columnsState.notifyDidInsertPhantom(toColumnId);
       });
     });
   }
 
-  void _updatePhantomRecord(
+  /// Reset or initial the [PhantomRecord]
+  ///
+  ///
+  /// * [columnId] the id of the column
+  /// * [dragTargetData]
+  /// * [dragTargetIndex]
+  ///
+  void _resetPhantomRecord(
     String columnId,
     FlexDragTargetData dragTargetData,
-    int index,
+    int dragTargetIndex,
   ) {
     // Log.debug('[$BoardPhantomController] move Column${dragTargetData.reorderFlexId}:${dragTargetData.draggingIndex} '
     //     'to Column$columnId:$index');
 
     phantomRecord = PhantomRecord(
       toColumnId: columnId,
-      toColumnIndex: index,
-      item: dragTargetData.reorderFlexItem as ColumnItem,
+      toColumnIndex: dragTargetIndex,
       fromColumnId: dragTargetData.reorderFlexId,
       fromColumnIndex: dragTargetData.draggingIndex,
     );
@@ -170,18 +179,15 @@ class BoardPhantomController extends OverlapReorderFlexDragTargetDelegate
     int dragTargetIndex,
   ) {
     if (phantomRecord == null) {
-      _updatePhantomRecord(reorderFlexId, dragTargetData, dragTargetIndex);
+      _resetPhantomRecord(reorderFlexId, dragTargetData, dragTargetIndex);
       _insertPhantom(reorderFlexId, dragTargetData, dragTargetIndex);
       return false;
     }
 
     final isNewDragTarget = phantomRecord!.toColumnId != reorderFlexId;
     if (isNewDragTarget) {
-      /// Remove the phantom in the previous column.
       _removePhantom(phantomRecord!.toColumnId);
-
-      /// Update the record and insert the phantom to new column.
-      _updatePhantomRecord(reorderFlexId, dragTargetData, dragTargetIndex);
+      _resetPhantomRecord(reorderFlexId, dragTargetData, dragTargetIndex);
       _insertPhantom(reorderFlexId, dragTargetData, dragTargetIndex);
     }
 
@@ -191,7 +197,6 @@ class BoardPhantomController extends OverlapReorderFlexDragTargetDelegate
   @override
   void updateDragTargetData(
     String reorderFlexId,
-    FlexDragTargetData dragTargetData,
     int dragTargetIndex,
   ) {
     phantomRecord?.updateInsertedIndex(dragTargetIndex);
@@ -199,14 +204,20 @@ class BoardPhantomController extends OverlapReorderFlexDragTargetDelegate
     assert(phantomRecord != null);
     if (phantomRecord!.toColumnId == reorderFlexId) {
       /// Update the existing phantom index
-      _updatePhantom(
-          phantomRecord!.toColumnId, dragTargetData, dragTargetIndex);
+      _updatePhantom(phantomRecord!.toColumnId, dragTargetIndex);
     }
   }
 }
 
+/// Use [PhantomRecord] to record where to remove the column item and where to
+/// insert the column item.
+///
+/// [fromColumnId] the column that phantom comes from
+/// [fromColumnIndex] the index of the phantom from the original column
+/// [toColumnId] the column that the phantom moves into
+/// [toColumnIndex] the index of the phantom moves into the column
+///
 class PhantomRecord {
-  final ColumnItem item;
   final String fromColumnId;
   int fromColumnIndex;
 
@@ -214,7 +225,6 @@ class PhantomRecord {
   int toColumnIndex;
 
   PhantomRecord({
-    required this.item,
     required this.toColumnId,
     required this.toColumnIndex,
     required this.fromColumnId,
@@ -274,7 +284,7 @@ class PassthroughPhantomContext extends FakeDragTargetEventTrigger
   final FlexDragTargetData dragTargetData;
 
   @override
-  Size? get feedbackSize => dragTargetData.state.feedbackSize;
+  Size? get feedbackSize => dragTargetData.feedbackSize;
 
   Widget? get draggingWidget => dragTargetData.draggingWidget;
 

frontend/app_flowy/packages/flowy_board/lib/src/widgets/phantom/phantom_state.dart

@@ -1,8 +1,8 @@
 import 'phantom_controller.dart';
 import 'package:flutter/material.dart';
 
-class ColumnPassthroughStateController {
-  final _states = <String, ColumnPassthrougPhantomhState>{};
+class ColumnPhantomStateController {
+  final _states = <String, ColumnState>{};
 
   void setColumnIsDragging(String columnId, bool isDragging) {
     _stateWithId(columnId).isDragging = isDragging;
@@ -32,17 +32,17 @@ class ColumnPassthroughStateController {
     _stateWithId(columnId).notifier.remove();
   }
 
-  ColumnPassthrougPhantomhState _stateWithId(String columnId) {
+  ColumnState _stateWithId(String columnId) {
     var state = _states[columnId];
     if (state == null) {
-      state = ColumnPassthrougPhantomhState();
+      state = ColumnState();
       _states[columnId] = state;
     }
     return state;
   }
 }
 
-class ColumnPassthrougPhantomhState {
+class ColumnState {
   bool isDragging = false;
   final notifier = PassthroughPhantomNotifier();
 }