From ba9875be0c58642a3aca63c06a4e5e2ce5389478 Mon Sep 17 00:00:00 2001
From: X Code <singerdmx@gmail.com>
Date: Sun, 19 Dec 2021 09:45:56 -0800
Subject: [PATCH] Add comments

---
 lib/src/models/rules/delete.dart |  8 ++++++++
 lib/src/models/rules/format.dart |  1 +
 lib/src/models/rules/insert.dart | 15 +++++++++++++++
 lib/src/models/rules/rule.dart   |  2 ++
 4 files changed, 26 insertions(+)

diff --git a/lib/src/models/rules/delete.dart b/lib/src/models/rules/delete.dart
index 91e884d9..caf8cf6a 100644
--- a/lib/src/models/rules/delete.dart
+++ b/lib/src/models/rules/delete.dart
@@ -2,6 +2,7 @@ import '../documents/attribute.dart';
 import '../quill_delta.dart';
 import 'rule.dart';
 
+/// A heuristic rule for delete operations.
 abstract class DeleteRule extends Rule {
   const DeleteRule();
 
@@ -46,6 +47,12 @@ class CatchAllDeleteRule extends DeleteRule {
   }
 }
 
+/// Preserves line format when user deletes the line's newline character
+/// effectively merging it with the next line.
+///
+/// This rule makes sure to apply all style attributes of deleted newline
+/// to the next available newline, which may reset any style attributes
+/// already present there.
 class PreserveLineStyleOnMergeRule extends DeleteRule {
   const PreserveLineStyleOnMergeRule();
 
@@ -101,6 +108,7 @@ class PreserveLineStyleOnMergeRule extends DeleteRule {
   }
 }
 
+/// Prevents user from merging a line containing an embed with other lines.
 class EnsureEmbedLineRule extends DeleteRule {
   const EnsureEmbedLineRule();
 
diff --git a/lib/src/models/rules/format.dart b/lib/src/models/rules/format.dart
index 634808e4..e1833b7c 100644
--- a/lib/src/models/rules/format.dart
+++ b/lib/src/models/rules/format.dart
@@ -2,6 +2,7 @@ import '../documents/attribute.dart';
 import '../quill_delta.dart';
 import 'rule.dart';
 
+/// A heuristic rule for format (retain) operations.
 abstract class FormatRule extends Rule {
   const FormatRule();
 
diff --git a/lib/src/models/rules/insert.dart b/lib/src/models/rules/insert.dart
index a8acb0e9..57b7117f 100644
--- a/lib/src/models/rules/insert.dart
+++ b/lib/src/models/rules/insert.dart
@@ -5,6 +5,7 @@ import '../documents/style.dart';
 import '../quill_delta.dart';
 import 'rule.dart';
 
+/// A heuristic rule for insert operations.
 abstract class InsertRule extends Rule {
   const InsertRule();
 
@@ -18,6 +19,10 @@ abstract class InsertRule extends Rule {
   }
 }
 
+/// Preserves line format when user splits the line into two.
+///
+/// This rule ignores scenarios when the line is split on its edge, meaning
+/// a newline is inserted at the beginning or the end of a line.
 class PreserveLineStyleOnSplitRule extends InsertRule {
   const PreserveLineStyleOnSplitRule();
 
@@ -198,6 +203,11 @@ class AutoExitBlockRule extends InsertRule {
   }
 }
 
+/// Resets format for a newly inserted line when insert occurred at the end
+/// of a line (right before a newline).
+///
+/// This handles scenarios when a new line is added when at the end of a
+/// heading line. The newly added line should be a regular paragraph.
 class ResetLineFormatOnNewLineRule extends InsertRule {
   const ResetLineFormatOnNewLineRule();
 
@@ -227,6 +237,7 @@ class ResetLineFormatOnNewLineRule extends InsertRule {
   }
 }
 
+/// Handles all format operations which manipulate embeds.
 class InsertEmbedsRule extends InsertRule {
   const InsertEmbedsRule();
 
@@ -275,6 +286,8 @@ class InsertEmbedsRule extends InsertRule {
   }
 }
 
+/// Applies link format to text segment (which looks like a link) when user
+/// inserts space character after it.
 class AutoFormatLinksRule extends InsertRule {
   const AutoFormatLinksRule();
 
@@ -314,6 +327,7 @@ class AutoFormatLinksRule extends InsertRule {
   }
 }
 
+/// Preserves inline styles when user inserts text inside formatted segment.
 class PreserveInlineStylesRule extends InsertRule {
   const PreserveInlineStylesRule();
 
@@ -359,6 +373,7 @@ class PreserveInlineStylesRule extends InsertRule {
   }
 }
 
+/// Fallback rule which simply inserts text as-is without any special handling.
 class CatchAllInsertRule extends InsertRule {
   const CatchAllInsertRule();
 
diff --git a/lib/src/models/rules/rule.dart b/lib/src/models/rules/rule.dart
index c9a0f911..f01eb438 100644
--- a/lib/src/models/rules/rule.dart
+++ b/lib/src/models/rules/rule.dart
@@ -19,6 +19,8 @@ abstract class Rule {
 
   void validateArgs(int? len, Object? data, Attribute? attribute);
 
+  /// Applies heuristic rule to an operation on a [document] and returns
+  /// resulting [Delta].
   Delta? applyRule(Delta document, int index,
       {int? len, Object? data, Attribute? attribute});