From 7d6f872fed7ae2c941d6023693d5e3867791251b Mon Sep 17 00:00:00 2001
From: Vincent Chan <okcdz@diverse.space>
Date: Fri, 12 Aug 2022 14:07:21 +0800
Subject: [PATCH] feat(doc): EditorState

---
 .../flowy_editor/lib/src/editor_state.dart        | 15 +++++++++++++--
 .../flowy_editor/lib/src/undo_manager.dart        |  6 ++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/frontend/app_flowy/packages/flowy_editor/lib/src/editor_state.dart b/frontend/app_flowy/packages/flowy_editor/lib/src/editor_state.dart
index bc55860c24..6b7210cd7a 100644
--- a/frontend/app_flowy/packages/flowy_editor/lib/src/editor_state.dart
+++ b/frontend/app_flowy/packages/flowy_editor/lib/src/editor_state.dart
@@ -2,7 +2,6 @@ import 'dart:async';
 import 'package:flowy_editor/src/service/service.dart';
 import 'package:flutter/material.dart';
 
-import 'package:flowy_editor/src/document/node.dart';
 import 'package:flowy_editor/src/document/selection.dart';
 import 'package:flowy_editor/src/document/state_tree.dart';
 import 'package:flowy_editor/src/operation/operation.dart';
@@ -35,6 +34,14 @@ enum CursorUpdateReason {
 /// [EditorState] also includes the services of the editor:
 /// - Selection service
 /// - Scroll service
+/// - Keyboard service
+/// - Input service
+/// - Toolbar service
+///
+/// In consideration of collaborative editing.
+/// All the mutations should be applied through [Transaction].
+///
+/// Mutating the document with document's API is not recommended.
 class EditorState {
   final StateTree document;
 
@@ -48,7 +55,6 @@ class EditorState {
     return _cursorSelection;
   }
 
-  /// add the set reason in the future, don't use setter
   updateCursorSelection(Selection? cursorSelection,
       [CursorUpdateReason reason = CursorUpdateReason.others]) {
     // broadcast to other users here
@@ -66,8 +72,13 @@ class EditorState {
     undoManager.state = this;
   }
 
+  /// Apply the transaction to the state.
+  ///
+  /// The options can be used to determine whether the editor
+  /// should record the transaction in undo/redo stack.
   apply(Transaction transaction,
       [ApplyOptions options = const ApplyOptions()]) {
+    // TODO: validate the transation.
     for (final op in transaction.operations) {
       _applyOperation(op);
     }
diff --git a/frontend/app_flowy/packages/flowy_editor/lib/src/undo_manager.dart b/frontend/app_flowy/packages/flowy_editor/lib/src/undo_manager.dart
index b81e91481f..e49debdd09 100644
--- a/frontend/app_flowy/packages/flowy_editor/lib/src/undo_manager.dart
+++ b/frontend/app_flowy/packages/flowy_editor/lib/src/undo_manager.dart
@@ -18,6 +18,11 @@ class HistoryItem extends LinkedListEntry<HistoryItem> {
 
   HistoryItem();
 
+  /// Seal the history item.
+  /// When an item is sealed, no more operations can be added
+  /// to the item.
+  ///
+  /// The caller should create a new [HistoryItem].
   seal() {
     _sealed = true;
   }
@@ -32,6 +37,7 @@ class HistoryItem extends LinkedListEntry<HistoryItem> {
     operations.addAll(iterable);
   }
 
+  /// Create a new [Transaction] by inverting the operations.
   Transaction toTransaction(EditorState state) {
     final builder = TransactionBuilder(state);
     for (var i = operations.length - 1; i >= 0; i--) {