Add comments

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();
 

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();
 

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();
 

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});