Improve the documentation

lib/src/models.dart

@@ -128,21 +128,25 @@ class HighlightDetails {
 /// For instance a1 is (0, 0), a2 is (0, 1), etc.
 @immutable
 class Coord {
+  /// Create a new [Coord] with the provided values.
   const Coord({
     required this.x,
     required this.y,
   })  : assert(x >= 0 && x <= 7),
         assert(y >= 0 && y <= 7);
 
+  /// Construct a [Coord] from a square identifier such as 'e2', 'c3', etc.
   Coord.fromSquareId(SquareId id)
       : x = id.codeUnitAt(0) - 97,
         y = id.codeUnitAt(1) - 49;
 
   final int x;
   final int y;
 
+  /// Gets the square identifier of the coordinate.
   SquareId get squareId => allSquares[8 * x + y];
 
+  /// Returns the offset of the coordinate on the board based on the orientation.
   Offset offset(Side orientation, double squareSize) {
     final dx = (orientation == Side.black ? 7 - x : x) * squareSize;
     final dy = (orientation == Side.black ? y : 7 - y) * squareSize;

lib/src/widgets/animation.dart

@@ -2,8 +2,17 @@ import 'package:flutter/widgets.dart';
 import '../models.dart';
 import './piece.dart';
 
-class PieceTranslation extends StatefulWidget {
-  const PieceTranslation({
+@Deprecated('Use AnimatedPieceTranslation instead')
+typedef PieceTranslation = AnimatedPieceTranslation;
+
+/// A widget that animates the translation of a piece from one square to another.
+///
+/// The piece will move from [fromCoord] to [toCoord] with the given [orientation].
+/// When the animation completes, [onComplete] will be called.
+/// The animation duration and curve can be customized.
+class AnimatedPieceTranslation extends StatefulWidget {
+  /// Creates an [AnimatedPieceTranslation] widget.
+  const AnimatedPieceTranslation({
     super.key,
     required this.child,
     required this.fromCoord,
@@ -15,23 +24,36 @@ class PieceTranslation extends StatefulWidget {
   })  : duration = duration ?? const Duration(milliseconds: 150),
         curve = curve ?? Curves.easeInOutCubic;
 
+  /// The widget to animate. Typically a [PieceWidget].
   final Widget child;
+
+  /// The coordinate of the square the piece is moving from.
   final Coord fromCoord;
+
+  /// The coordinate of the square the piece is moving to.
   final Coord toCoord;
+
+  /// The orientation of the board.
   final Side orientation;
+
+  /// Called when the animation completes.
   final void Function() onComplete;
+
+  /// The duration of the animation.
   final Duration duration;
+
+  /// The curve of the animation.
   final Curve curve;
 
   int get orientationFactor => orientation == Side.white ? 1 : -1;
   double get dx => -(toCoord.x - fromCoord.x).toDouble() * orientationFactor;
   double get dy => (toCoord.y - fromCoord.y).toDouble() * orientationFactor;
 
   @override
-  State<PieceTranslation> createState() => _PieceTranslationState();
+  State<AnimatedPieceTranslation> createState() => _PieceTranslationState();
 }
 
-class _PieceTranslationState extends State<PieceTranslation>
+class _PieceTranslationState extends State<AnimatedPieceTranslation>
     with SingleTickerProviderStateMixin {
   late final AnimationController _controller = AnimationController(
     duration: widget.duration,
@@ -68,8 +90,13 @@ class _PieceTranslationState extends State<PieceTranslation>
   }
 }
 
-class PieceFadeOut extends StatefulWidget {
-  const PieceFadeOut({
+@Deprecated('Use AnimatedPieceFadeOut instead')
+typedef PieceFadeOut = AnimatedPieceFadeOut;
+
+/// A widget that plays a fade out animation on a piece.
+class AnimatedPieceFadeOut extends StatefulWidget {
+  /// Creates an [AnimatedPieceFadeOut] widget.
+  const AnimatedPieceFadeOut({
     super.key,
     required this.piece,
     required this.size,
@@ -82,20 +109,35 @@ class PieceFadeOut extends StatefulWidget {
   })  : duration = duration ?? const Duration(milliseconds: 150),
         curve = curve ?? Curves.easeInQuad;
 
+  /// The piece to fade out.
   final Piece piece;
+
+  /// The size of the piece.
   final double size;
+
+  /// The assets used to render the piece.
   final PieceAssets pieceAssets;
+
+  /// If `true` the piece will be hidden.
   final bool blindfoldMode;
+
+  /// If `true` the piece will be displayed upside down.
   final bool upsideDown;
+
+  /// The duration of the animation.
   final Duration duration;
+
+  /// The curve of the animation.
   final Curve curve;
+
+  /// Called when the animation completes.
   final void Function() onComplete;
 
   @override
-  State<PieceFadeOut> createState() => _PieceFadeOutState();
+  State<AnimatedPieceFadeOut> createState() => _PieceFadeOutState();
 }
 
-class _PieceFadeOutState extends State<PieceFadeOut>
+class _PieceFadeOutState extends State<AnimatedPieceFadeOut>
     with TickerProviderStateMixin {
   late final AnimationController _controller = AnimationController(
     duration: widget.duration,

lib/src/widgets/board.dart

@@ -225,7 +225,7 @@ class _BoardState extends State<Board> {
           size: widget.squareSize,
           orientation: widget.data.orientation,
           squareId: entry.key,
-          child: PieceFadeOut(
+          child: AnimatedPieceFadeOut(
             duration: widget.settings.animationDuration,
             piece: entry.value,
             size: widget.squareSize,
@@ -259,7 +259,7 @@ class _BoardState extends State<Board> {
           size: widget.squareSize,
           orientation: widget.data.orientation,
           squareId: entry.key,
-          child: PieceTranslation(
+          child: AnimatedPieceTranslation(
             fromCoord: entry.value.$1.coord,
             toCoord: entry.value.$2.coord,
             orientation: widget.data.orientation,

lib/src/widgets/board_annotation.dart

@@ -2,6 +2,9 @@ import 'dart:async';
 import 'package:flutter/widgets.dart';
 import '../models.dart';
 
+/// A widget that displays an annotation of a square on the board.
+///
+/// This is typically used to display move annotations, such as "!!" or "??".
 class BoardAnnotation extends StatefulWidget {
   final Annotation annotation;
 

lib/src/widgets/highlight.dart

@@ -3,6 +3,11 @@ import 'package:flutter/material.dart';
 import 'package:flutter/widgets.dart';
 import '../models.dart';
 
+/// A widget that displays a board highlight.
+///
+/// Board highlights can be a solid color or an image. They are used to
+/// highlight squares on the board, such as the last move, or the selected
+/// square.
 class Highlight extends StatelessWidget {
   const Highlight({
     super.key,
@@ -36,6 +41,9 @@ class Highlight extends StatelessWidget {
   }
 }
 
+/// A widget that displays a check highlight.
+///
+/// Check highlights are used to indicate that a king is in check.
 class CheckHighlight extends StatelessWidget {
   const CheckHighlight({super.key, required this.size});
 
@@ -69,6 +77,9 @@ class CheckHighlight extends StatelessWidget {
   }
 }
 
+/// A widget that displays a move destination.
+///
+/// Move destinations are used to indicate where a piece can move to.
 class MoveDest extends StatelessWidget {
   const MoveDest({
     super.key,
@@ -100,6 +111,10 @@ class MoveDest extends StatelessWidget {
   }
 }
 
+/// A widget that displays an occupied move destination.
+///
+/// Occupied move destinations are used to indicate where a piece can move to
+/// on a square that is already occupied by a piece.
 class OccupiedMoveDest extends StatelessWidget {
   const OccupiedMoveDest({
     super.key,

lib/src/widgets/piece.dart

@@ -2,7 +2,7 @@ import 'dart:math' as math;
 import 'package:flutter/widgets.dart';
 import '../models.dart';
 
-/// Widget that displays a chess piece
+/// Widget that displays a chess piece.
 class PieceWidget extends StatelessWidget {
   const PieceWidget({
     super.key,
@@ -14,22 +14,22 @@ class PieceWidget extends StatelessWidget {
     this.upsideDown = false,
   });
 
-  /// Specifies the role and color of the piece
+  /// Specifies the role and color of the piece.
   final Piece piece;
 
-  /// Size of the board square the piece will occupy
+  /// Size of the board square the piece will occupy.
   final double size;
 
-  /// Piece set
+  /// Piece set.
   final PieceAssets pieceAssets;
 
-  /// Pieces are hidden in blindfold mode
+  /// Pieces are hidden in blindfold mode.
   final bool blindfoldMode;
 
-  /// If `true` the piece is displayed rotated by 180 degrees
+  /// If `true` the piece is displayed rotated by 180 degrees.
   final bool upsideDown;
 
-  /// Use this value to animate the opacity of the piece
+  /// This value is used to animate the opacity of the piece.
   final Animation<double>? opacity;
 
   @override

lib/src/widgets/positioned_square.dart

@@ -1,9 +1,10 @@
 import 'package:flutter/widgets.dart';
 import '../models.dart';
+import './highlight.dart';
 
 /// Board aware Positioned widget
 ///
-/// Use to position things, such as [Piece], [Highlight] on the board.
+/// Use to position things, such as [Piece] or [Highlight] on the board.
 /// Since it's a wrapper over a [Positioned] widget it must be a descendant of a
 /// [Stack].
 class PositionedSquare extends StatelessWidget {

lib/src/widgets/promotion.dart

@@ -2,6 +2,12 @@ import 'package:flutter/widgets.dart';
 import '../models.dart';
 import 'piece.dart';
 
+/// A widget that allows the user to select a promotion piece.
+///
+/// This widget should be displayed when a pawn reaches the last rank and must be
+/// promoted. The user can select a piece to promote to by tapping on one of
+/// the four pieces displayed.
+/// Promotion can be canceled by tapping outside the promotion widget.
 class PromotionSelector extends StatelessWidget {
   const PromotionSelector({
     super.key,

lib/src/widgets/shape.dart

@@ -4,6 +4,9 @@ import 'package:flutter/widgets.dart';
 import '../models.dart';
 import 'positioned_square.dart';
 
+/// A Widget that displays a shape overlay on the board.
+///
+/// Typically used to display arrows, circles, and piece masks on the board.
 class ShapeWidget extends StatelessWidget {
   const ShapeWidget({
     super.key,
@@ -12,8 +15,15 @@ class ShapeWidget extends StatelessWidget {
     required this.orientation,
   });
 
+  /// The shape to display on the board.
+  ///
+  /// Currently supported shapes are [Arrow], [Circle], and [PieceShape].
   final Shape shape;
+
+  /// Size of the board the shape will overlay.
   final double boardSize;
+
+  /// Orientation of the board.
   final Side orientation;
 
   double get squareSize => boardSize / 8;