docs: documented z_canvas_component

packages/pinball_flame/lib/src/z_canvas_component.dart

@@ -1,11 +1,14 @@
-// ignore_for_file: public_member_api_docs
-
 import 'dart:typed_data';
 import 'dart:ui';
 
 import 'package:flame/components.dart';
 
+/// {@template z_canvas_component}
+/// Draws [ZIndex] components after the all non-[ZIndex] components have been
+/// drawn.
+/// {@endtemplate}
 class ZCanvasComponent extends Component {
+  /// {@macro z_canvas_component}
   ZCanvasComponent({
     Iterable<Component>? children,
   })  : _pinballCanvas = ZCanvas(),
@@ -21,7 +24,17 @@ class ZCanvasComponent extends Component {
   }
 }
 
+/// Apply to any [Component] that will be rendered according to a
+/// [ZIndex.zIndex].
+///
+/// [ZIndex] components must be descendants of a [ZCanvasComponent].
+///
+/// {@macro z_canvas.render}
 mixin ZIndex on Component {
+  /// The z-index of this component.
+  ///
+  /// The higher the value, the later the component will be drawn. Hence,
+  /// rendering in front of [Component]s with lower [zIndex] values.
   int zIndex = 0;
 
   @override
@@ -36,13 +49,30 @@ mixin ZIndex on Component {
   }
 }
 
+/// The [ZCanvas] allows to postpone the rendering of [ZIndex] components.
+///
+/// You should not use this class directly.
 class ZCanvas implements Canvas {
+  /// The [Canvas] to render to.
+  ///
+  /// This is set by [ZCanvasComponent] when rendering.
   late Canvas canvas;
 
   final List<ZIndex> _zBuffer = [];
 
-  void buffer(ZIndex rendering) => _zBuffer.add(rendering);
-
+  /// Postpones the rendering of [ZIndex] component and its children.
+  void buffer(ZIndex component) => _zBuffer.add(component);
+
+  /// Renders all [ZIndex] components and their children.
+  ///
+  /// {@template z_canvas.render}
+  /// The rendering order is defined by the parent [ZIndex]. The children of
+  /// the same parent are rendered in the order they were added.
+  ///
+  /// If two [Component]s ever overlap each other, and have the same
+  /// [ZIndex.zIndex], there is no guarantee that the first one will be rendered
+  /// before the second one.
+  /// {@endtemplate}
   void render() => _zBuffer
     ..sort((a, b) => a.zIndex.compareTo(b.zIndex))
     ..whereType<Component>().forEach(_render)