chore: update doc

Author: appflowy

frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board.dart

@@ -110,7 +110,7 @@ class AppFlowyBoard extends StatelessWidget {
             scrollManager!._groupState = _groupState;
           }
 
-          return AFBoardContent(
+          return _AppFlolwyBoardContent(
             config: config,
             dataController: dataController,
             scrollController: scrollController,
@@ -131,7 +131,7 @@ class AppFlowyBoard extends StatelessWidget {
   }
 }
 
-class AFBoardContent extends StatefulWidget {
+class _AppFlolwyBoardContent extends StatefulWidget {
   final ScrollController? scrollController;
   final OnDragStarted? onDragStarted;
   final OnReorder onReorder;
@@ -143,21 +143,13 @@ class AFBoardContent extends StatefulWidget {
   final BoxConstraints columnConstraints;
   final AFBoardScrollManager? scrollManager;
   final BoardGroupsState columnsState;
-
-  ///
   final AppFlowyBoardCardBuilder cardBuilder;
-
-  ///
   final AppFlowyBoardHeaderBuilder? headerBuilder;
-
-  ///
   final AppFlowyBoardFooterBuilder? footerBuilder;
-
   final OverlapDragTargetDelegate delegate;
-
   final BoardPhantomController phantomController;
 
-  const AFBoardContent({
+  const _AppFlolwyBoardContent({
     required this.config,
     required this.onReorder,
     required this.delegate,
@@ -178,12 +170,12 @@ class AFBoardContent extends StatefulWidget {
         super(key: key);
 
   @override
-  State<AFBoardContent> createState() => _AFBoardContentState();
+  State<_AppFlolwyBoardContent> createState() => _AppFlowyBoardContentState();
 }
 
-class _AFBoardContentState extends State<AFBoardContent> {
+class _AppFlowyBoardContentState extends State<_AppFlolwyBoardContent> {
   final GlobalKey _boardContentKey =
-      GlobalKey(debugLabel: '$AFBoardContent overlay key');
+      GlobalKey(debugLabel: '$_AppFlolwyBoardContent overlay key');
   late BoardOverlayEntry _overlayEntry;
 
   final Map<String, GlobalObjectKey> _reorderFlexKeys = {};
@@ -263,7 +255,7 @@ class _AFBoardContentState extends State<AFBoardContent> {
           value: widget.dataController.getGroupController(columnData.id),
           child: Consumer<AFBoardGroupDataController>(
             builder: (context, value, child) {
-              final boardColumn = AppFlowyBoardGroupWidget(
+              final boardColumn = AppFlowyBoardGroup(
                 reorderFlexKey: reorderFlexKey,
                 // key: PageStorageKey<String>(columnData.id),
                 margin: _marginFromIndex(columnIndex),
@@ -351,12 +343,12 @@ class BoardGroupContext {
 
 class BoardGroupsState extends DraggingStateStorage
     with ReorderDragTargetIndexKeyStorage {
-  /// Quick access to the [AppFlowyBoardGroupWidget]
+  /// Quick access to the [AppFlowyBoardGroup]
   final Map<String, GlobalKey> groupKeys = {};
   final Map<String, DraggingState> groupDragStates = {};
   final Map<String, Map<String, GlobalObjectKey>> groupDragDragTargets = {};
 
-  void addGroup(String groupId, AppFlowyBoardGroupWidget groupWidget) {
+  void addGroup(String groupId, AppFlowyBoardGroup groupWidget) {
     groupKeys[groupId] = groupWidget.reorderFlexKey;
   }
 

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

@@ -60,9 +60,9 @@ abstract class AppFlowyBoardGroupDataDataSource extends ReoderFlexDataSource {
   }
 }
 
-/// [AppFlowyBoardGroupWidget] represents the column of the Board.
+/// [AppFlowyBoardGroup] represents the group of the Board.
 ///
-class AppFlowyBoardGroupWidget extends StatefulWidget {
+class AppFlowyBoardGroup extends StatefulWidget {
   final AppFlowyBoardGroupDataDataSource dataSource;
   final ScrollController? scrollController;
   final ReorderFlexConfig config;
@@ -94,7 +94,7 @@ class AppFlowyBoardGroupWidget extends StatefulWidget {
 
   final GlobalObjectKey reorderFlexKey;
 
-  const AppFlowyBoardGroupWidget({
+  const AppFlowyBoardGroup({
     Key? key,
     required this.reorderFlexKey,
     this.headerBuilder,
@@ -116,13 +116,12 @@ class AppFlowyBoardGroupWidget extends StatefulWidget {
         super(key: key);
 
   @override
-  State<AppFlowyBoardGroupWidget> createState() =>
-      _AppFlowyBoardGroupWidgetState();
+  State<AppFlowyBoardGroup> createState() => _AppFlowyBoardGroupState();
 }
 
-class _AppFlowyBoardGroupWidgetState extends State<AppFlowyBoardGroupWidget> {
+class _AppFlowyBoardGroupState extends State<AppFlowyBoardGroup> {
   final GlobalKey _columnOverlayKey =
-      GlobalKey(debugLabel: '$AppFlowyBoardGroupWidget overlay key');
+      GlobalKey(debugLabel: '$AppFlowyBoardGroup overlay key');
   late BoardOverlayEntry _overlayEntry;
 
   @override

frontend/app_flowy/packages/appflowy_board/lib/src/widgets/board_data.dart

@@ -28,16 +28,42 @@ typedef OnMoveGroupItemToGroup = void Function(
   int toIndex,
 );
 
+/// A controller for [AppFlowyBoard] widget.
+///
+/// A [AppFlowyBoardDataController] can be used to provide an initial value of
+/// the board by calling [addGroup] method with the passed in parameter
+/// [AppFlowyBoardGroupData]. A [AppFlowyBoardGroupData] represents one
+/// group data. Whenever the user modifies the board, this controller will
+/// update the corresponding group data.
+///
+/// Also, you can register the callbacks that receive the changes.
+/// [onMoveGroup] will get called when moving the group from one position to
+/// another.
+///
+/// [onMoveGroupItem] will get called when moving the group's items.
+///
+/// [onMoveGroupItemToGroup] will get called when moving the group's item from
+/// one group to another group.
 class AppFlowyBoardDataController extends ChangeNotifier
     with EquatableMixin, BoardPhantomControllerDelegate, ReoderFlexDataSource {
   final List<AppFlowyBoardGroupData> _groupDatas = [];
+
+  /// [onMoveGroup] will get called when moving the group from one position to
+  /// another.
   final OnMoveGroup? onMoveGroup;
+
+  /// [onMoveGroupItem] will get called when moving the group's items.
   final OnMoveGroupItem? onMoveGroupItem;
+
+  /// [onMoveGroupItemToGroup] will get called when moving the group's item from
+  /// one group to another group.
   final OnMoveGroupItemToGroup? onMoveGroupItemToGroup;
 
+  /// Returns the unmodifiable list of [AppFlowyBoardGroupData]
   UnmodifiableListView<AppFlowyBoardGroupData> get groupDatas =>
       UnmodifiableListView(_groupDatas);
 
+  /// Returns list of group id
   List<String> get groupIds =>
       _groupDatas.map((groupData) => groupData.id).toList();
 
@@ -50,6 +76,10 @@ class AppFlowyBoardDataController extends ChangeNotifier
     this.onMoveGroupItemToGroup,
   });
 
+  /// Adds a new group to the end of the current group list.
+  ///
+  /// If you don't want to notify the listener after adding a new group, the
+  /// [notify] should set to false. Default value is true.
   void addGroup(AppFlowyBoardGroupData groupData, {bool notify = true}) {
     if (_groupControllers[groupData.id] != null) return;
 
@@ -59,6 +89,10 @@ class AppFlowyBoardDataController extends ChangeNotifier
     if (notify) notifyListeners();
   }
 
+  /// Adds a list of groups to the end of the current group list.
+  ///
+  /// If you don't want to notify the listener after adding the groups, the
+  /// [notify] should set to false. Default value is true.
   void addGroups(List<AppFlowyBoardGroupData> groups, {bool notify = true}) {
     for (final column in groups) {
       addGroup(column, notify: false);
@@ -67,6 +101,10 @@ class AppFlowyBoardDataController extends ChangeNotifier
     if (groups.isNotEmpty && notify) notifyListeners();
   }
 
+  /// Removes the group with id [groupId]
+  ///
+  /// If you don't want to notify the listener after removing the group, the
+  /// [notify] should set to false. Default value is true.
   void removeGroup(String groupId, {bool notify = true}) {
     final index = _groupDatas.indexWhere((group) => group.id == groupId);
     if (index == -1) {
@@ -82,6 +120,10 @@ class AppFlowyBoardDataController extends ChangeNotifier
     }
   }
 
+  /// Removes a list of groups
+  ///
+  /// If you don't want to notify the listener after removing the groups, the
+  /// [notify] should set to false. Default value is true.
   void removeGroups(List<String> groupIds, {bool notify = true}) {
     for (final groupId in groupIds) {
       removeGroup(groupId, notify: false);
@@ -90,12 +132,16 @@ class AppFlowyBoardDataController extends ChangeNotifier
     if (groupIds.isNotEmpty && notify) notifyListeners();
   }
 
+  /// Remove all the groups controller.
+  /// This method should get called when you want to remove all the current
+  /// groups or get ready to reinitialize the [AppFlowyBoard].
   void clear() {
     _groupDatas.clear();
     _groupControllers.clear();
     notifyListeners();
   }
 
+  /// Returns the [AFBoardGroupDataController] with id [groupId].
   AFBoardGroupDataController? getGroupController(String groupId) {
     final groupController = _groupControllers[groupId];
     if (groupController == null) {
@@ -105,6 +151,11 @@ class AppFlowyBoardDataController extends ChangeNotifier
     return groupController;
   }
 
+  /// Moves the group controller from [fromIndex] to [toIndex] and notify the
+  /// listeners.
+  ///
+  /// If you don't want to notify the listener after moving the group, the
+  /// [notify] should set to false. Default value is true.
   void moveGroup(int fromIndex, int toIndex, {bool notify = true}) {
     final toGroupData = _groupDatas[toIndex];
     final fromGroupData = _groupDatas.removeAt(fromIndex);
@@ -114,44 +165,55 @@ class AppFlowyBoardDataController extends ChangeNotifier
     if (notify) notifyListeners();
   }
 
+  /// Moves the group's item from [fromIndex] to [toIndex]
+  /// If the group with id [groupId] is not exist, this method will do nothing.
   void moveGroupItem(String groupId, int fromIndex, int toIndex) {
     if (getGroupController(groupId)?.move(fromIndex, toIndex) ?? false) {
       onMoveGroupItem?.call(groupId, fromIndex, toIndex);
     }
   }
 
+  /// Adds the [AppFlowyGroupItem] to the end of the group
+  /// If the group with id [groupId] is not exist, this method will do nothing.
   void addGroupItem(String groupId, AppFlowyGroupItem item) {
     getGroupController(groupId)?.add(item);
   }
 
+  /// Inserts the [AppFlowyGroupItem] at [index] in the group
+  /// It will do nothing if the group with id [groupId] is not exist
   void insertGroupItem(String groupId, int index, AppFlowyGroupItem item) {
     getGroupController(groupId)?.insert(index, item);
   }
 
+  /// Removes the item with id [itemId] from the group
+  /// It will do nothing if the group with id [groupId] is not exist
   void removeGroupItem(String groupId, String itemId) {
     getGroupController(groupId)?.removeWhere((item) => item.id == itemId);
   }
 
+  /// Replaces or inserts the [AppFlowyGroupItem] to the end of the group.
+  /// If the group with id [groupId] is not exist, this method will do nothing.
   void updateGroupItem(String groupId, AppFlowyGroupItem item) {
     getGroupController(groupId)?.replaceOrInsertItem(item);
   }
 
+  /// Swap the
   @override
   @protected
-  void swapGroupItem(
+  void moveGroupItemToAnotherGroup(
     String fromGroupId,
     int fromGroupIndex,
     String toGroupId,
     int toGroupIndex,
   ) {
     final fromGroupController = getGroupController(fromGroupId)!;
     final toGroupController = getGroupController(toGroupId)!;
-    final item = fromGroupController.removeAt(fromGroupIndex);
+    final fromGroupItem = fromGroupController.removeAt(fromGroupIndex);
     if (toGroupController.items.length > toGroupIndex) {
       assert(toGroupController.items[toGroupIndex] is PhantomGroupItem);
     }
 
-    toGroupController.replace(toGroupIndex, item);
+    toGroupController.replace(toGroupIndex, fromGroupItem);
     onMoveGroupItemToGroup?.call(
       fromGroupId,
       fromGroupIndex,

frontend/app_flowy/packages/appflowy_board/lib/src/widgets/reorder_phantom/phantom_controller.dart

@@ -27,7 +27,7 @@ abstract class BoardPhantomControllerDelegate {
   /// [dragTargetIndex] the index of the dragTarget
   void updatePhantom(String groupId, int newIndex);
 
-  void swapGroupItem(
+  void moveGroupItemToAnotherGroup(
     String fromGroupId,
     int fromGroupIndex,
     String toGroupId,
@@ -79,7 +79,7 @@ class BoardPhantomController extends OverlapDragTargetDelegate
     }
 
     if (phantomRecord!.toGroupId == groupId) {
-      delegate.swapGroupItem(
+      delegate.moveGroupItemToAnotherGroup(
         fromGroupId,
         phantomRecord!.fromGroupIndex,
         toGroupId,