Add doc comments and resolve analyzer issues

Author: Jjagg

README.md

@@ -1,4 +1,4 @@
-# Boustro
+# boustro
 
 Boustro is a rich text editor for Flutter.
 
@@ -31,7 +31,7 @@ Boustro is split into 3 packages that are layered on top of each other.
 text possible and data structures to represent text formats and formatted
 text. The structure is similar to Android's [Spannable](https://developer.android.com/reference/android/text/Spannable).
 1. [boustro](packages/boustro): The actual rich text editor.
-1. [boustro_starter](packages/boustro_starter): Attributes, line modifiers and embeds to get started with.
+1. [boustro_starter](packages/boustro_starter): Attributes, line modifiers and embeds to get started with boustro.
 
 ## Limitations
 

docs/README.md

@@ -0,0 +1,4 @@
+# Boustro Documentation
+
+This is a stub for in-depth documentation for boustro.
+

example/lib/main.dart

@@ -1,5 +1,3 @@
-import 'package:boustro/src/scope.dart';
-import 'package:built_collection/built_collection.dart';
 import 'package:boustro/boustro.dart';
 import 'package:boustro_starter/boustro_starter.dart';
 import 'package:boustro_starter/toolbar_items.dart' as toolbar_items;
@@ -114,9 +112,9 @@ class BulletListParagraphHandler extends LineParagraphModifier {
     Map<String, Object> properties,
     Widget child,
   ) {
-    return CharacterLeadingMarginModifier(
+    return LeadingTextModifier(
       padding: 8,
-      character: '\u2022',
+      text: '\u2022',
       child: child,
     );
   }

packages/analysis_options.yaml

@@ -25,10 +25,10 @@ linter:
     avoid_annotating_with_dynamic: false
     avoid_as: false
     avoid_returning_null: false
+    cascade_invocations: false
+    flutter_style_todos: false
     lines_longer_than_80_chars: false
+    prefer_constructors_over_static_methods: false
     prefer_double_quotes: false
     prefer_expression_function_bodies: false
-    flutter_style_todos: false
     unnecessary_final: false
-    unnecessary_this: false
-    prefer_constructors_over_static_methods: false

packages/boustro/lib/src/context.dart

@@ -4,7 +4,6 @@ import 'package:flutter/widgets.dart';
 
 import 'document.dart';
 import 'scope.dart';
-import 'widgets/document_controller.dart';
 import 'widgets/editor.dart';
 
 /// Determines how a [BoustroEditor] displays a
@@ -17,7 +16,7 @@ class BoustroContext {
     List<ParagraphEmbedBuilder>? embedHandlers,
   }) : this._(
           lineHandlers ?? const [],
-          {for (var h in embedHandlers ?? <ParagraphEmbedBuilder>[]) h.key: h},
+          {for (var h in embedHandlers ?? <ParagraphEmbedBuilder>[]) h.type: h},
         );
 
   BoustroContext._(
@@ -40,10 +39,11 @@ class BoustroContext {
 ///
 /// Each key should map to one handler.
 abstract class ParagraphEmbedBuilder {
+  /// Constant base constructor for implementations.
   const ParagraphEmbedBuilder();
 
   /// Identifier for this embed.
-  String get key;
+  String get type;
 
   /// Function that builds the embed widget.
   Widget buildEmbed(
@@ -53,7 +53,9 @@ abstract class ParagraphEmbedBuilder {
   ]);
 }
 
+/// Wraps a line to modify how it's displayed.
 abstract class LineParagraphModifier {
+  /// Constant base constructor for implementations.
   const LineParagraphModifier();
 
   /// Determines the order in which line handlers are applied.

packages/boustro/lib/src/convert/convert_delta.dart

@@ -54,7 +54,7 @@ class EmbedCodec {
   /// Create an embed codec.
   const EmbedCodec(this.key, this.decoder, this.encoder);
 
-  /// Identifies the type of the embed. See [ParagraphEmbedBuilder.key].
+  /// Identifies the type of the embed. See [ParagraphEmbedBuilder.type].
   final String key;
 
   /// Decoder for the embed value.

packages/boustro/lib/src/document.dart

@@ -3,7 +3,10 @@ import 'package:equatable/equatable.dart';
 import 'package:flutter/foundation.dart';
 import 'package:flutter_spanned_controller/flutter_spanned_controller.dart';
 
+import 'context.dart';
+
 /// Rich text represented as a list of [BoustroParagraph]s.
+@immutable
 class BoustroDocument {
   /// Create a new boustro document.
   const BoustroDocument(this.paragraphs);
@@ -12,7 +15,7 @@ class BoustroDocument {
   final BuiltList<BoustroParagraph> paragraphs;
 }
 
-/// A paragraph in a [BoustroDocument]. Is either a [BoustroLine] for rich text
+/// A paragraph in a [BoustroDocument]. Is either a [BoustroLine] for rich text,
 /// or a [BoustroParagraphEmbed] for other content.
 @immutable
 abstract class BoustroParagraph extends Equatable {
@@ -33,33 +36,34 @@ abstract class BoustroParagraph extends Equatable {
   ) =>
       BoustroParagraphEmbed(type, value);
 
+  /// Execute [line] if this is a [BoustroLine] and [embed] if this is a
+  /// [BoustroParagraphEmbed].
   T match<T>({
     required T Function(BoustroLine) line,
     required T Function(BoustroParagraphEmbed) embed,
   });
 
+  /// Same as [match], but directly get the members of this paragraph.
   T deconstruct<T>({
     required T Function(
             String text, SpanList spans, BuiltMap<String, Object> properties)
         line,
     required T Function(String type, Object value) embed,
   });
-
-  int get length => match(
-        embed: (_) => 1,
-        line: (l) => l.text.length,
-      );
 }
 
+/// Immutable representation of a line of rich text in a [BoustroDocument].
 @immutable
 class BoustroLine extends BoustroParagraph {
+  /// Create a boustro line.
   BoustroLine(
     this.text,
     this.spanList, {
     BuiltMap<String, Object>? properties,
   })  : properties = properties ?? BuiltMap<String, Object>(),
         super._();
 
+  /// Create a boustro line with the text and spans of [spannedText].
   BoustroLine.fromSpanned(
     SpannedString spannedText, {
     BuiltMap<String, Object>? properties,
@@ -100,15 +104,32 @@ class BoustroLine extends BoustroParagraph {
   }
 }
 
+/// Immutable representation of an embed in boustro.
+///
+/// Embeds are represented with a [type] that's used to find the matching
+/// [ParagraphEmbedBuilder] and a [value] which the builder uses to build a
+/// widget. The expected runtime type of [value] should be specified by the
+/// builder.
 @immutable
 class BoustroParagraphEmbed extends BoustroParagraph {
+  /// Create an embed.
   const BoustroParagraphEmbed(this.type, this.value) : super._();
 
+  /// Create a copy of this embed with [this.value] replaced with [value].
   BoustroParagraphEmbed withValue(Object value) {
     return BoustroParagraphEmbed(type, value);
   }
 
+  /// Type of the embed.
+  ///
+  /// Matched with [ParagraphEmbedBuilder.type] to find the builder that can
+  /// translate [value] into a widget.
   final String type;
+
+  /// Value of the embed.
+  ///
+  /// Can be any type, but should be of a type expected by the matching builder
+  /// for [type].
   final Object value;
 
   @override

packages/boustro/lib/src/result.dart

@@ -1,23 +1,52 @@
+import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 
+import 'document.dart';
 import 'widgets/document_controller.dart';
+import 'widgets/editor.dart';
 
+/// Inherited widget that carries information about a boustro document.
+@immutable
 class BoustroScope extends InheritedWidget {
-  BoustroScope.editable({
-    required DocumentController controller,
+  /// Create a scope for an editable document with a document controller.
+  const BoustroScope.editable({
+    Key? key,
+    required DocumentController this.controller,
     required Widget child,
-  })   : controller = controller,
-        super(child: child);
+  })   : document = null,
+        super(key: key, child: child);
 
-  BoustroScope.readonly({
+  /// Create a scope for a read-only document with a boustro document controller.
+  const BoustroScope.readonly({
+    Key? key,
+    required BoustroDocument this.document,
     required Widget child,
   })   : controller = null,
-        super(child: child);
+        super(key: key, child: child);
 
+  /// Document controller of the editor. Null if [BoustroScope.readonly] was
+  /// used.
   final DocumentController? controller;
 
-  bool get editable => controller != null;
+  /// Document of the [BoustroView]. Null if [BoustroScope.readonly] was
+  /// used.
+  final BoustroDocument? document;
 
+  /// True if [BoustroScope.editable] was used, false if [BoustroScope.readonly]
+  /// was used.
+  bool get isEditable => controller != null;
+
+  /// Call [editable] if [isEditable] is true or [readonly] if it is not.
+  T match<T>({
+    required T Function(DocumentController) editable,
+    required T Function(BoustroDocument) readonly,
+  }) {
+    return isEditable ? editable(controller!) : readonly(document!);
+  }
+
+  /// Look for a boustro scope widget up the tree from [context].
+  ///
+  /// Throws if there is no [BoustroScope] ancestor.
   static BoustroScope of(BuildContext context) {
     final scope = context.dependOnInheritedWidgetOfExactType<BoustroScope>();
     if (scope == null) {
@@ -42,6 +71,17 @@ class BoustroScope extends InheritedWidget {
 
   @override
   bool updateShouldNotify(covariant BoustroScope oldWidget) {
-    return editable != oldWidget.editable;
+    return isEditable != oldWidget.isEditable;
+  }
+
+  @override
+  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
+    super.debugFillProperties(properties);
+    properties
+      ..add(DiagnosticsProperty<bool>('isEditable', isEditable))
+      ..add(DiagnosticsProperty<DocumentController?>('controller', controller,
+          defaultValue: null))
+      ..add(DiagnosticsProperty<BoustroDocument?>('document', document,
+          defaultValue: null));
   }
 }

packages/boustro/lib/src/scope.dart

@@ -13,22 +13,28 @@ abstract class ParagraphState {
   /// Create a paragraph.
   const ParagraphState({required FocusNode focusNode}) : _focusNode = focusNode;
 
-  /// Use to focus this paragraph.
   final FocusNode _focusNode;
+
+  /// Manages focus for this paragraph.
   FocusNode get focusNode => _focusNode;
 
+  /// Discards resources used by this object.
   @mustCallSuper
   void dispose() {
     focusNode.dispose();
   }
 
+  /// Execute [line] if this is a [LineState] and [embed] if this is an
+  /// [EmbedState].
   T match<T>({
     required T Function(LineState) line,
     required T Function(EmbedState) embed,
   });
 }
 
 /// Holds focus node and state for a line of text.
+///
+/// This is the editable variant of [BoustroLine].
 @immutable
 class LineState extends ParagraphState {
   /// Create a text line.
@@ -39,6 +45,8 @@ class LineState extends ParagraphState {
   })  : properties = properties ?? BuiltMap<String, Object>(),
         super(focusNode: focusNode);
 
+  /// Create a copy of this line state, but with properties set to the new
+  /// properties.
   LineState withProperties(
     Map<String, dynamic> properties,
   ) {
@@ -70,7 +78,9 @@ class LineState extends ParagraphState {
       line(this);
 }
 
-/// Holds [FocusNode] for a boustro embed.
+/// Holds [FocusNode] and content for a boustro embed.
+///
+/// This is the editable variant of [BoustroParagraphEmbed].
 @immutable
 class EmbedState extends ParagraphState {
   /// Create an embed.
@@ -79,6 +89,8 @@ class EmbedState extends ParagraphState {
     required this.content,
   }) : super(focusNode: focusNode);
 
+  /// Create a copy of this embed state, but with the value of its content set
+  /// to the new value.
   EmbedState withValue(Object value) {
     return EmbedState(
       focusNode: focusNode,
@@ -89,14 +101,6 @@ class EmbedState extends ParagraphState {
   /// Content of the embed.
   final BoustroParagraphEmbed content;
 
-  @override
-  void dispose() {
-    try {
-      (content.value as dynamic).dispose();
-    } catch (NoSuchMethodError) {}
-    super.dispose();
-  }
-
   @override
   T match<T>({
     required T Function(LineState) line,
@@ -276,6 +280,7 @@ class DocumentController extends ValueNotifier<BuiltList<ParagraphState>> {
     return newLine;
   }
 
+  /// Set the [LineState.properties] for [line].
   void setLineProperties(LineState line, Map<String, dynamic> properties) {
     final lineIndex = paragraphs.indexWhere((l) => l is LineState && l == line);
     if (lineIndex < 0) {
@@ -290,6 +295,9 @@ class DocumentController extends ValueNotifier<BuiltList<ParagraphState>> {
     );
   }
 
+  /// Remove the focused paragraph.
+  ///
+  /// Does nothing if [focusedParagraph] is null.
   void removeCurrentParagraph() {
     final index = focusedParagraphIndex;
     if (index != null) {