Add comments on ParagraphCache

lib/src/ui/paragraph_cache.dart

@@ -3,18 +3,29 @@ import 'dart:ui';
 import 'package:flutter/widgets.dart';
 import 'package:quiver/collection.dart';
 
+/// A cache of laid out [Paragraph]s. This is used to avoid laying out the same
+/// text multiple times, which is expensive.
 class ParagraphCache {
   ParagraphCache(int maximumSize)
       : _cache = LruMap<int, Paragraph>(maximumSize: maximumSize);
 
   final LruMap<int, Paragraph> _cache;
 
+  /// Returns a [Paragraph] for the given [key]. [key] is the same as the
+  /// key argument to [performAndCacheLayout].
   Paragraph? getLayoutFromCache(int key) {
     return _cache[key];
   }
 
+  /// Applies [style] and [textScaleFactor] to [text] and lays it out to create
+  /// a [Paragraph]. The [Paragraph] is cached and can be retrieved with the
+  /// same [key] by calling [getLayoutFromCache].
   Paragraph performAndCacheLayout(
-      String text, TextStyle style, double textScaleFactor, int key) {
+    String text,
+    TextStyle style,
+    double textScaleFactor,
+    int key,
+  ) {
     final builder = ParagraphBuilder(style.getParagraphStyle());
     builder.pushStyle(style.getTextStyle(textScaleFactor: textScaleFactor));
     builder.addText(text);
@@ -26,10 +37,14 @@ class ParagraphCache {
     return paragraph;
   }
 
+  /// Clears the cache. This should be called when the same text and style
+  /// pair no longer produces the same layout. For example, when a font is
+  /// loaded.
   void clear() {
     _cache.clear();
   }
 
+  /// Returns the number of [Paragraph]s in the cache.
   int get length {
     return _cache.length;
   }