Merge pull request #69 from garak/improve-wording

📝 fix wording in docs and code

README.md

@@ -1,10 +1,10 @@
 # Chess
 
-Chess is a PHP chess library that is used for chess move
+Chess is a PHP chess library used for chess move
 generation/validation, piece placement/movement, and check/checkmate/stalemate
 detection - basically everything but the AI. 
 
-NOTE: this started as a port of [chess.js](https://github.com/jhlywa/chess.js) for php, forked from [ryanhs/chess.php](https://github.com/ryanhs/chess.php)
+NOTE: this started as a port of [chess.js](https://github.com/jhlywa/chess.js) for PHP, forked from [ryanhs/chess.php](https://github.com/ryanhs/chess.php)
 
 [![Latest Stable Version](https://poser.pugx.org/p-chess/chess/v/stable)](https://packagist.org/p-chess/chess)
 [![MIT License](https://poser.pugx.org/p-chess/chess/license)](https://packagist.org/packages/p-chess/chess)  
@@ -100,13 +100,13 @@ echo $output->render($chess);
 
 <img src="https://user-images.githubusercontent.com/179866/112304837-411be280-8c9e-11eb-8333-c2489f9bef05.png">        
 
-See [dedicated documentation](docs/output_imagine.md) for a detailed instructions.
+See [dedicated documentation](docs/output_imagine.md) for detailed instructions.
 
 ### HTML
 
 Pieces are displayed inside an HTML table.
 
-See [dedicated documentation](docs/output_html.md) for a detailed instructions.
+See [dedicated documentation](docs/output_html.md) for detailed instructions.
 
 ## Performance
 
@@ -126,3 +126,4 @@ There is still a lot to do in this topic.
 ## Other documentation
 
 All classes are documented in the [docs directory](docs/index.md).
+

docs/board.md

@@ -17,17 +17,18 @@ foreach ($board as $offset => $piece) {
 ```
 
 The only method that can be directly used is `$board->reverse()`, useful to toggle sides (e.g. to see
-the board from black point of view, and then from white again).
+the board from the black point of view, and then from the white again).
 
 The following static methods can be used if you need to deal
 with [SAN](https://en.wikipedia.org/wiki/Algebraic_notation_(chess)):
 
-* `rank()`: get the rank of a square, as number between 1 and 8
-* `file()`: get the file of a square, as number between 1 and 8
-* `algebraic()`: get the SAN of a square, as string (e.g. "e2").
+* `rank()`: get the rank of a square, as a number between 1 and 8
+* `file()`: get the file of a square, as a number between 1 and 8
+* `algebraic()`: get the SAN of a square, as a string (e.g. "e2").
    This should be the same as calling `Board::SQUARES[$square]`
 
 Such methods accept an integer square (see `SQUARES` constant). 
 
 Useful constants represent starting board (`Board::DEFAULT_POSITION`) and empty board (`Board::EMPTY`)
 in [FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation) notation.
+

docs/chess.md

@@ -8,9 +8,9 @@ It represents a chess game.
 ### `__construct(?string $fen, ?History $history)`
 
 This is the main method. If you invoke it without arguments, you simply get an instance of the class.
-If you decide to start a game from a particular position, you can pass it as first argument,
+If you decide to start a game from a particular position, you can pass it as the first argument,
 in [FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation) notation.
-Also, you can pass an [`\Pchess\Chess\History`](history.md) object (that is supposed to be consistent
+Also, you can pass a [`\Pchess\Chess\History`](history.md) object (which is supposed to be consistent
 with the first argument, even if no check is performed).
 
 ## Move-related
@@ -20,15 +20,15 @@ with the first argument, even if no check is performed).
 The main method used to move a piece from a starting position to an ending position.
 You can provide such information as a string in [SAN](https://en.wikipedia.org/wiki/Algebraic_notation_(chess))
 notation (e.g. "Nxb7") or as an array with `from` and `to` keys. A possible `promotion` key can be used too.
-If move is legal, a [`\Pchess\Chess\Move`](move.md) object is returned.
+If the move is legal, a [`\Pchess\Chess\Move`](move.md) object is returned.
 
 ### `undo(): ?Move`
 
-Cancels the last move (that is returned). If no move is present in history, method returns `null`;
+Cancels the last move (that is returned). If no move is present in history, the method returns `null`;
 
 ### `moves(int $square): array`
 
-Gets a list of allowed moves. If you pass a square, only move originating from that square are returned.
+Gets a list of allowed moves. If you pass a square, only moves originating from that square are returned.
 Otherwise, every possible move is returned.
 The square must be passed as an integer, as coded in the [`\Pchess\Chess\Board::SQUARES`](board.md) constant.
 
@@ -43,7 +43,7 @@ the [`\Pchess\Chess\Board::SQUARES`](board.md) constant.
 
 Alters the board, by putting a new [`\Pchess\Chess\Piece`](piece.md) in a square.
 The square must be passed a string, as coded in the [`\Pchess\Chess\Board::SQUARES`](board.md) constant.
-Please note that you cannot put two Kings of same color on the board. If you do so, method returns `false`.
+Please note that you cannot put two Kings of the same color on the board. If you do so, the method returns `false`.
 
 ## Game situation controls
 
@@ -57,15 +57,15 @@ Controls if there's a checkmate.
 
 ### `inStalemate(): bool`
 
-Controls if there's a stalemate (i.e. king cannot do any legal move).
+Controls if there's a stalemate (i.e., the king cannot make any legal move).
 
 ### `insufficientMaterial(): bool`
 
 Controls if material is insufficient to continue the game (e.g. only kings are left).
 
 ### `inThreefoldRepetition(): bool`
 
-Controls if same moves were repeated in last three turns.
+Controls if the same moves were repeated in the last three turns.
 
 ### `halfMovesExceeded(): bool`
 
@@ -77,7 +77,7 @@ Controls if there is a draw.
 
 ### `gameOver(): bool`
 
-Controls if game is over.
+Controls if the game is over.
 
 ## Utilities
 
@@ -89,9 +89,10 @@ Gets the current position in [FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%9
 
 Gets [`\Pchess\Chess\Board\History`](history.md) object.
 
-## Public properties
+## Public Properties
 
 | Property | Type   | Description               |
 |----------|--------|---------------------------|
 | `$board` | Board  | [Board object](board.md)  |
 | `$turn`  | string | current turn ("w" or "b") |
+

docs/move.md

@@ -20,8 +20,8 @@ The following public properties are available:
 Squares are coded like in keys and/or values of `\Pchess\Chess\Board::SQUARES`
 Notation is [SAN](https://en.wikipedia.org/wiki/Algebraic_notation_(chess))
 
-Move can be built directly with is contructor, passing all arguments in respective order.
-Or it can be built using static method `Move::buildMove()`:
+`Move` can be built directly with its constructor, passing all arguments in respective order.
+Or it can be built using the static method `Move::buildMove()`:
 
 ```php
 public static function buildMove(
@@ -47,3 +47,4 @@ The information about move type, stored in `$flags` properties as bits, is:
 | 16  | PROMOTION    | Promotion           |
 | 32  | KSIDE_CASTLE | Short castling      |
 | 64  | QSIDE_CASTLE | Long castling       |
+

docs/output_html.md

@@ -1,6 +1,6 @@
 # Output with HTML
 
-This option requires extending provided `HtmlOutput` class, since you need to define
+This option requires extending provided the `HtmlOutput` class, since you need to define
 a way to build links for pieces.
 
 The following is an example of a possible extension.

docs/output_imagine.md

@@ -52,5 +52,5 @@ public function __construct(
 );
 ```
 
-In this directory, you can find a utility script, named [get-resources.sh](get-resources.sh), that downloads
+In this directory, you can find a utility script, named [get-resources.sh](get-resources.sh), which downloads
 all pieces images from Wikimedia, plus a free font to use.

docs/piece.md

@@ -2,11 +2,12 @@
 
 The `\Pchess\Chess\Piece` class is a simple value object representing a piece in [`\Pchess\Chess\Chess`](chess.md).
 
-The object is composed by a `$type` and a `$color` (both are a single-character string).
+The object is composed of a `$type` and a `$color` (both are a single-character string).
 
-Type can be "k", "q", "r", "b", "n", or "p" (respectively King, Queen, Rook, Bishop, Knight, or Pawn).
+The type can be "k", "q", "r", "b", "n", or "p" (respectively King, Queen, Rook, Bishop, Knight, or Pawn).
 
-Color can be "b" (black) or "w" (white).
+The color can be "b" (black) or "w" (white).
 
-String representation is piece type, in uppercase when white and in lowercase when black.
+The string representation is piece type, in uppercase when white and in lowercase when black.
 For example, "B" is a white Bishop, while "q" is a black Queen. 
+

src/Chess.php

@@ -197,7 +197,7 @@ public function get(string $square): ?Piece
             return null;
         }
 
-        return $this->board[Board::SQUARES[$square]]; // shorcut?
+        return $this->board[Board::SQUARES[$square]]; // shortcut?
     }
 
     public function put(Piece $piece, string $square): bool
@@ -733,7 +733,7 @@ public function insufficientMaterial(): bool
     }
 
     /* TODO: while this function is fine for casual use, a better
-     * implementation would use a Zobrist key (instead of FEN). the
+     * implementation would use a Zobrist key (instead of FEN). The
      * Zobrist key would be maintained in the make_move/undo_move functions,
      * avoiding the costly that we do below.
      */

src/Validation.php

@@ -93,7 +93,7 @@ public static function validateFen(string $fen): int
             }
         }
 
-        // 11th criterion: en-passant if last is black's move, then its must be white turn
+        // 11th criterion: en-passant if last is black's move, then it must be white turn
         if (\strlen($tokens[3]) > 1) {
             if (($tokens[3][1] === '3' && $tokens[1] === Piece::WHITE) ||
                 ($tokens[3][1] === '6' && $tokens[1] === Piece::BLACK)) {

tests/AttackTest.php

@@ -176,7 +176,7 @@ public function testInsufficientMaterial(): void
         self::assertTrue($chess->insufficientMaterial());
     }
 
-    public function testinThreefoldRepetition(): void
+    public function testInThreefoldRepetition(): void
     {
         $chess = new ChessPublicator();
 

tests/ConstructorTest.php

@@ -46,7 +46,7 @@ public function testUnicodeOutput(): void
         self::assertStringContainsString('♙ ', $output->render($chess));
     }
 
-    public function testReversedeOutput(): void
+    public function testReversedOutput(): void
     {
         $chess = new Chess();
         $output = new Output\AsciiOutput();