Improve documentation

.gitignore

@@ -10,3 +10,5 @@ build/
 pubspec.lock
 
 example/*.exe
+
+doc/api/

lib/dartchess.dart

@@ -1,3 +1,6 @@
+/// Dart chess library for native platforms only.
+///
+/// The API is entirely immutable.
 library dartchess;
 
 export 'src/constants.dart';

lib/src/board.dart

@@ -3,7 +3,7 @@ import './models.dart';
 import './attacks.dart';
 import './utils.dart';
 
-/// [Piece] positions on a board.
+/// A board represented by several square sets for each piece.
 class Board {
   const Board({
     required this.occupied,

lib/src/constants.dart

@@ -1,9 +1,20 @@
 const kFileNames = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h'];
 const kRankNames = ['1', '2', '3', '4', '5', '6', '7', '8'];
 
+/// The board part of the initial position in the FEN format.
 const kInitialBoardFEN = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR';
+
+/// Initial position in the Extended Position Description format.
 const kInitialEPD = '$kInitialBoardFEN w KQkq -';
+
+/// Initial position in the FEN format.
 const kInitialFEN = '$kInitialEPD 0 1';
+
+/// Empty board part in the FEN format.
 const kEmptyBoardFEN = '8/8/8/8/8/8/8/8';
+
+/// Empty board in the EPD format.
 const kEmptyEPD = '$kEmptyBoardFEN w - -';
+
+/// Empty board in the FEN format.
 const kEmptyFEN = '$kEmptyEPD 0 1';

lib/src/debug.dart

@@ -4,7 +4,11 @@ import './models.dart';
 import './position.dart';
 import './utils.dart';
 
-/// Takes a string like:
+/// Takes a string and returns a SquareSet. Useful for debugging/testing purposes.
+///
+/// Example:
+/// ```dart
+/// final str = '''
 /// . 1 1 1 . . . .
 /// . 1 . 1 . . . .
 /// . 1 . . 1 . . .
@@ -13,8 +17,10 @@ import './utils.dart';
 /// . 1 . . . 1 . .
 /// . 1 . . . 1 . .
 /// . 1 . . 1 . . .
-///
-/// and returns a SquareSet. Useful for debugging/testing purposes.
+/// '''
+/// final squareSet = makeSquareSet(str);
+/// // SquareSet(0x0E0A12221E222212)
+/// ```
 SquareSet makeSquareSet(String rep) {
   SquareSet ret = SquareSet.empty;
   final table = rep

lib/src/position.dart

@@ -6,9 +6,9 @@ import './board.dart';
 import './setup.dart';
 import './utils.dart';
 
-/// A playable chess or chess variant position.
+/// A base class for playable chess or chess variant positions.
 ///
-/// See [Chess] for a concrete implementation.
+/// See [Chess] for a concrete implementation of standard rules.
 abstract class Position<T extends Position<T>> {
   const Position({
     required this.board,
@@ -37,6 +37,7 @@ abstract class Position<T extends Position<T>> {
   /// Current move number.
   final int fullmoves;
 
+  /// Abstract const constructor to be used by subclasses.
   const Position._initial()
       : board = Board.standard,
         turn = Color.white,
@@ -575,6 +576,7 @@ abstract class Position<T extends Position<T>> {
   }
 }
 
+/// A standard chess position.
 class Chess extends Position<Chess> {
   const Chess({
     required super.board,
@@ -628,6 +630,7 @@ class Chess extends Position<Chess> {
   }
 }
 
+/// A variant of chess where captures cause an explosion to the surrounding pieces.
 class Atomic extends Position<Atomic> {
   const Atomic({
     required super.board,
@@ -831,6 +834,7 @@ class Atomic extends Position<Atomic> {
   }
 }
 
+/// The outcome of a [Position]. No `winner` means a draw.
 class Outcome {
   const Outcome({this.winner});
 
@@ -866,8 +870,7 @@ enum IllegalSetup {
   /// Such a position cannot be reached by any sequence of legal moves.
   impossibleCheck,
 
-  /// There are pawns on the backrank. Only [Horde] allows players to
-  /// have pawns on their own backrank.
+  /// There are pawns on the backrank.
   pawnsOnBackrank,
 
   /// A king is missing, or there are too many kings.

lib/src/square_set.dart

@@ -4,7 +4,7 @@ import './models.dart';
 /// rank-file (LERF) mapping.
 ///
 /// This is how the mapping looks like:
-///
+/// ```
 ///  8 | 56 57 58 59 60 61 62 63
 ///  7 | 48 49 50 51 52 53 54 55
 ///  6 | 40 41 42 43 44 45 46 47
@@ -15,7 +15,7 @@ import './models.dart';
 ///  1 | 0  1  2  3  4  5  6  7
 ///    -------------------------
 ///      a  b  c  d  e  f  g  h
-///
+/// ```
 class SquareSet {
   /// Creates a [SquareSet] with the provided 64bit integer value.
   const SquareSet(this.value);

test/debug_test.dart

@@ -14,6 +14,7 @@ void main() {
 . 1 . . 1 . . .
 ''';
     final sq = makeSquareSet(rep);
+    print(sq);
 
     expect(rep, printSquareSet(sq));
     expect(makeSquareSet('''