From 4c16108321412f4ccc120ffd1dbcd7be8012c05c Mon Sep 17 00:00:00 2001 From: Jeroen De Meerleer Date: Sun, 17 Nov 2019 01:23:11 +0100 Subject: [PATCH] CHANGE: Phpdoc is used again for docs generation --- CHANGELOG.md | 1 + Makefile | 2 +- src/Game.php | 37 +++++-- src/Pairing.php | 36 +++++-- src/Player.php | 75 ++++++++++--- src/Readers/Pairtwo6.php | 37 ++++--- src/Readers/Swar4.php | 61 ++++++++--- src/Round.php | 2 +- src/Tournament.php | 220 ++++++++++++++++++++++++++++----------- 9 files changed, 353 insertions(+), 118 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aa5b5ba..001a823 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ * MAJOR CHANGE: Getter and setter methods have been removed. (Please see [0d8a325](https://github.com/JeroenED/libpairtwo/commit/0d8a325eb501b775830f68fa6f600f9f4ca5588c) for more info) * CHANGE: Some fields has been renamed to match coding guideline (Please see [1ab96fa](https://github.com/JeroenED/libpairtwo/commit/1ab96fa04782c1b0f2b6bb9d1bac8397a74ab38e) for more info) * CHANGE: Logo has been redesigned +* CHANGE: Phpdoc is used again for docs generation * REMOVED: `Tiebreak::American` and all its uses were removed (Please see [a6015ae](https://github.com/JeroenED/libpairtwo/commit/a6015ae8169f0973f4937605d0f807aacc233630) for more info) ## v1.2 (Release: 28-sep-2019) diff --git a/Makefile b/Makefile index 482a232..bcc9b8f 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ view-coverage: ## Shows the code coverage report open build/coverage/index.html api: ## Generates api-docs - VERSIONTAG=$(VERSION) doxygen + phpdoc -d ./src -t ./doc/api dist: ## Generates distribution cp dist/composer* res/ diff --git a/src/Game.php b/src/Game.php index ed9d287..00d379e 100644 --- a/src/Game.php +++ b/src/Game.php @@ -28,27 +28,51 @@ use DateTime; */ class Game { - /** @var Pairing | null */ + /** + * The pairing for this games as seen from white's side + * + * @var Pairing | null + */ public $White; - /** @var Pairing | null */ + /** + * The pairing for this games as seen from blacks's side + * + * @var Pairing | null + */ public $Black; - /** @var GameResult | null */ + /** + * The calculated game result + * + * @var GameResult | null + */ private $CalculatedResult; - /** @var int */ + /** + * The board where this game is held + * + * @var int + */ public $Board; + /** + * Returns fields that were not directly assigned. + * Class Game contains the special field Result containing the result of the game + * @param string $key + * @return Gameresult + */ public function __get(string $key) { if ($key == 'Result') { return $this->calculateResult(); } + return null; } /** - * Returns the result for the game + * Returns the result for the game. + * This method needs to be called from $Game->Result * * @return Gameresult */ @@ -86,8 +110,7 @@ class Game /** * Checks if 2 games are equal * - * @param Game $game1 - * @param Game $game2 + * @param Game $game * @return bool */ public function equals(Game $game): bool diff --git a/src/Pairing.php b/src/Pairing.php index 4583039..33dd05d 100644 --- a/src/Pairing.php +++ b/src/Pairing.php @@ -27,21 +27,45 @@ use JeroenED\Libpairtwo\Enums\Result; */ class Pairing { - /** @var Player | null */ + /** + * The player of the pairing. Please note this means the pairing was seen from the point of view of this player + * + * @var Player | null + */ public $Player; - /** @var Player | null */ + /** + * The opponent of player + * + * @var Player | null + */ public $Opponent; - /** @var Color */ + /** + * The color of the player. + * Possible values are Black and White + * + * @var Color + */ public $Color; - /** @var Result */ + /** + * The result of the Game. Possible values contain Won, Lost, Draw, Forfait, Bye, etc. + * @var Result + */ public $Result; - /** @var int */ + /** + * The round of the game + * + * @var int + */ public $Round; - /** @var int */ + /** + * The number of the board where the game was held + * + * @var int + */ public $Board; } diff --git a/src/Player.php b/src/Player.php index 15448c7..414805c 100644 --- a/src/Player.php +++ b/src/Player.php @@ -28,38 +28,83 @@ use DateTime; */ class Player { - /** @var string */ + /** + * Name of the player + * + * @var string + */ public $Name; - /** @var int[] */ + /** + * The player ids for the player. Possible keys are, but not limited to nation and fide + * + * @var int[] + */ public $Ids; - /** @var int[] */ + /** + * The Elos for the player. Possible keys are, but not limited to nation and fide + * + * @var int[] + */ public $Elos; - /** @var DateTime */ + /** + * Birthday of the player + * + * @var DateTime + */ public $DateOfBirth; - /** @var float[] */ + /** + * Tiebreak points of the player. These values are calculated when Tournament->Ranking is called + * + * @var float[] + */ public $Tiebreaks = []; - /** @var string */ + /** + * The nation the player belongs to. Be noted this does not actually mean this is his main nationality. A player can be signed USCF but may be Italian + * + * @var string + */ public $Nation; // TODO: Implement categories - /** @var string */ + /** + * The category the player belongs to + * + * @var string + */ public $Category; - /** @var Title */ + /** + * The title of the player. Possible values can be GM, IM, IA, etc. + * + * @var Title + */ public $Title; - /** @var Gender */ + /** + * The gender of the player. Possible values contain Male, Female and Neutral + * + * @var Gender + */ public $Gender; - /** @var Pairing[] */ + /** + * The pairings of the player + * + * @var Pairing[] + */ public $Pairings = []; - /** @var bool|DateTime|int|string[] */ + /** + * Binary data that was read out of the pairing file + * + * @var bool|DateTime|int|string[] + */ + private $BinaryData; /** @@ -214,6 +259,8 @@ class Player * * WARNING: Calculation currently incorrect. Uses the rule of 400 as temporary solution * + * @param $type + * @param $unratedElo * @return int */ public function Performance(string $type, int $unratedElo): float @@ -278,10 +325,10 @@ class Player * Sets binary data that is read out the pairing file but is not needed immediately * * @param string $key - * @param bool|int|DateTime|string $Valueey + * @param bool|int|DateTime|string $value */ - public function __set(string $key, $Valueey): void + public function __set(string $key, $value): void { - $this->BinaryData[$key] = $Valueey; + $this->BinaryData[$key] = $value; } } diff --git a/src/Readers/Pairtwo6.php b/src/Readers/Pairtwo6.php index f0a54c4..cce7ae1 100644 --- a/src/Readers/Pairtwo6.php +++ b/src/Readers/Pairtwo6.php @@ -2,7 +2,7 @@ /** * Reader Pairtwo6 * - * Reads out Pairtwo-6 files + * Reads out Pairtwo-6 and Pairtwo-5 files * * @author Jeroen De Meerleer * @category Main @@ -39,19 +39,30 @@ use DateTime; */ class Pairtwo6 implements ReaderInterface { - private const PT_DAYFACTOR = 32; - private const PT_MONTHFACTOR = 16; - private const PT_YEARFACTOR = 512; - private const PT_PASTOFFSET = 117; - private const CompatibleVersions = ['6.', '5.']; + const PT_DAYFACTOR = 32; + const PT_MONTHFACTOR = 16; + const PT_YEARFACTOR = 512; + const PT_PASTOFFSET = 117; + const CompatibleVersions = ['6.', '5.']; - /** @var string */ + /** + * Version of Pairtwo this file was created with + * + * @var string + */ public $Release; - /** @var Tournament */ + /** + * The tournament + * + * @var Tournament + */ public $Tournament; - /** @var bool|DateTime|int|string[] */ + /** + * Binary data that was read out of the pairing file + * @var bool|DateTime|int|string[] + */ private $BinaryData; /** @@ -72,15 +83,15 @@ class Pairtwo6 implements ReaderInterface * Sets binary data that is read out the pairtwo file but is not needed immediately * * @param string $key - * @param bool|int|DateTime|string $Valueey + * @param bool|int|DateTime|string $value */ - public function __set(string $key, $Valueey): void + public function __set(string $key, $value): void { - $this->BinaryData[$key] = $Valueey; + $this->BinaryData[$key] = $value; } /** - * Reads out $swsfile and returns a Pairtwo6 class object + * Actually reads the Swar-File * * @param string $filename * @throws IncompatibleReaderException diff --git a/src/Readers/Swar4.php b/src/Readers/Swar4.php index 22d0ed5..c5436fa 100644 --- a/src/Readers/Swar4.php +++ b/src/Readers/Swar4.php @@ -1,6 +1,6 @@ */ - - namespace JeroenED\Libpairtwo\Readers; use JeroenED\Libpairtwo\Enums\Color; @@ -28,24 +26,42 @@ use JeroenED\Libpairtwo\Tournament; use DateTime; /** - * Class Swar4 - * @package JeroenED\Libpairtwo\Readers + * Reader Swar4 + * + * Reads out Swar-4 files + * + * @author Jeroen De Meerleer + * @category Main + * @package Libpairtwo + * @copyright Copyright (c) 2018-2019 Jeroen De Meerleer */ class Swar4 implements ReaderInterface { - /** @var Tournament */ - public $Tournament; - - /** @var string */ + /** + * Version of Pairtwo this file was created with + * + * @var string + */ public $Release; - /** @var bool|int|DateTime|string[] */ + /** + * The tournament + * + * @var Tournament + */ + public $Tournament; + + /** + * Binary data that was read out of the pairing file + * + * @var bool|DateTime|int|string[] + */ private $BinaryData; /** @var array */ - private const CompatibleVersions = ['v4.']; + const CompatibleVersions = ['v4.']; - private const Tempos = [ + const Tempos = [ [ '105 min/40 moves + 15 min. QPF', '120 min/40 moves + 15 min. with incr. 30" starting from 40th move', @@ -105,6 +121,8 @@ class Swar4 implements ReaderInterface ]; /** + * Actually reads the Swar-File + * * @param string $filename * @throws IncompatibleReaderException */ @@ -496,6 +514,15 @@ class Swar4 implements ReaderInterface } /** + * Reads data of the filehandle and converts to $type. defaults to $default if given + * + * Possible types for $type are: + * * String (UTF-8 String representation of $data. Default: empty string '') + * * Hex (Capitalized Hex Value of $data. Default: 00) + * * Int (Unsigned Integer value of $data Default: 0) + * * Bool (Boolean representation of $data. Default: false) + * * Date (Date representation of $data. Default: 1902/01/01) + * * @param string $type * @param $handle * @param null $default @@ -580,14 +607,15 @@ class Swar4 implements ReaderInterface * Sets binary data that is read out the swar file but is not needed immediately * * @param string $key - * @param bool|int|DateTime|string $Valueey + * @param bool|int|DateTime|string $value */ - public function __set(string $key, $Valueey): void + public function __set(string $key, $value): void { - $this->BinaryData[$key] = $Valueey; + $this->BinaryData[$key] = $value; } /** + * Converts a swar-4 string to a \DateTime object * @param string $string * @return DateTime */ @@ -600,6 +628,9 @@ class Swar4 implements ReaderInterface } } + /** + * Adds the first tiebreak to the tournament + */ private function addTiebreaks(): void { switch ($this->Tournament->System) { diff --git a/src/Round.php b/src/Round.php index 0833a22..949872d 100644 --- a/src/Round.php +++ b/src/Round.php @@ -55,7 +55,7 @@ class Round */ public $Pairings = []; - /* + /** * Adds a game to the round * * @param Game $game diff --git a/src/Tournament.php b/src/Tournament.php index 71ae04c..c3074d4 100644 --- a/src/Tournament.php +++ b/src/Tournament.php @@ -1,8 +1,6 @@ * @category Main @@ -30,79 +28,178 @@ use DateTime; */ class Tournament { - /** @var string */ + /** + * Name of the Tournament + * + * @var string + */ public $Name; - /** @var string */ + /** + * Organiser of the tournament (eg. Donald J. Trump) + * + * + * @var string + */ public $Organiser; - /** @var int */ + /** + * Club ID of the tournament organiser (eg. 205001600) + * + * @var string + */ public $OrganiserClubNo; - /** @var string */ + /** + * Club name of the tournament organiser (eg. The White House Chess Club) + * + * @var string + */ public $OrganiserClub; - /** @var string */ + /** + * Place where the Tounament is held (eg. The Oval Office) + * + * @var string + */ public $OrganiserPlace; - /** @var string */ + /** + * The country where the tournament is held + * + * @var string + */ public $OrganiserCountry; - /** @var int */ + /** + * Whether or not the tournament is an official tournament and send to the world chess organisation + * + * @var int + */ public $FideHomol; - /** @var DateTime */ + /** + * Start date (First round or Players meeting) of the tournament + * @var DateTime + */ public $StartDate; - /** @var DateTime */ + /** + * End date (Last round or Award Ceremony) of the tournament + * + * @var DateTime + */ public $EndDate; - /** @var string[] */ + /** + * An Array of the assigned arbiters + * + * @var string[] + */ public $Arbiters; - /** @var int */ + /** + * Number of round the tournament has + * + * @var int + */ public $NoOfRounds; - /** @var Round[] */ + /** + * Round objects of all rounds in the tournament + * + * @var Round[] + */ public $Rounds = []; - /** @var string */ + /** + * The tempo of the tournament (eg. 90 min/40 moves + 30 sec. increment starting from move 1) + * @var string + */ public $Tempo; - /** @var int */ + /** + * The elo a player gets if he does not have an official elo + * + * @var int + */ public $NonRatedElo; - /** @var TournamentSystem */ + /** + * The system the tournament (eg. Swiss, Closed, American) + * + * @var TournamentSystem + */ public $System; - /** @var string */ + /** + * The tempo for the first period of a game in the tournament + * + * @var string + */ public $FirstPeriod; - /** @var string */ + /** + * The tempo for the second period of a game in the tournament + * + * @var string + */ public $SecondPeriod; - /** @var string */ + /** + * The federation for which this tournament is held + * + * @var string + */ public $Federation; - /** @var Player[] */ + /** + * All players of the tournament + * + * @var Player[] + */ public $Players = []; - /** @var int */ + /** + * The year or season the tournament is held or is count for + * + * @var int + */ public $Year; - /** @var Pairing[] */ + /** + * All pairings of the tournament + * + * @var Pairing[] + */ public $Pairings = []; - /** @var Tiebreak[] */ + /** + * The tiebreaks for the tournament + * + * @var Tiebreak[] + */ public $Tiebreaks = []; - /** @var string */ + /** + * The elo that priority above all others + * + * @var string + */ public $PriorityElo = 'Fide'; - /** @var string */ + /** + * The Id that has priority above all other + * + * @var string + */ public $PriorityId = 'Nation'; - /** @var bool|DateTime|int|string[] */ + /** + * Binary data that was read out of the pairing file + * + * @var bool|DateTime|int|string[] + */ private $BinaryData = []; /** @@ -381,8 +478,7 @@ class Tournament /** * Sort by tiebreak * - * @param Player $a - * @param Player $b + * @param int $key * @return Closure */ private function sortTiebreak(int $key): Closure @@ -402,9 +498,9 @@ class Tournament * @param Tiebreak $tiebreak * @param Player $player * @param int $tbkey - * @return float | null + * @return float */ - private function calculateTiebreak(Tiebreak $tiebreak, Player $player, int $tbkey = 0): ?float + private function calculateTiebreak(Tiebreak $tiebreak, Player $player, int $tbkey = 0): float { switch ($tiebreak) { case Tiebreak::Keizer: @@ -468,7 +564,7 @@ class Tournament return $player->Performance($this->PriorityElo, $this->NonRatedElo); break; default: - return null; + return 0; } } @@ -507,9 +603,9 @@ class Tournament * Points following keizer system * * @param Player $player - * @return float | null + * @return float */ - private function calculateKeizer(Player $player): ?float + private function calculateKeizer(Player $player): float { return $player->ScoreAmerican; } @@ -518,9 +614,9 @@ class Tournament * Number of points * * @param Player $player - * @return float | null + * @return float */ - private function calculatePoints(Player $player): ?float + private function calculatePoints(Player $player): float { return $player->calculatePoints(); } @@ -530,9 +626,9 @@ class Tournament * Number of won games * * @param Player $player - * @return float | null + * @return float */ - private function calculateBaumbach(Player $player): ?float + private function calculateBaumbach(Player $player): float { $totalwins = 0; foreach ($player->Pairings as $pairing) { @@ -550,9 +646,9 @@ class Tournament * Number of played games with black * * @param Player $player - * @return float | null + * @return float */ - private function calculateBlackPlayed(Player $player): ?float + private function calculateBlackPlayed(Player $player): float { $totalwins = 0; foreach ($player->Pairings as $pairing) { @@ -567,9 +663,9 @@ class Tournament * Number of won games with black * * @param Player $player - * @return float | null + * @return float */ - private function calculateBlackWin(Player $player): ?float + private function calculateBlackWin(Player $player): float { $totalwins = 0; foreach ($player->Pairings as $pairing) { @@ -587,9 +683,9 @@ class Tournament * @param Player $player * @param array $opponents * @param int $key - * @return float | null + * @return float */ - private function calculateMutualResult(Player $player, array $opponents, int $key): ?float + private function calculateMutualResult(Player $player, array $opponents, int $key): float { $interestingplayers = $opponents; if ($key != 0) { @@ -627,10 +723,11 @@ class Tournament * The average rating of the opponents * * @param Player $player + * @param string $type * @param int $cut * @return float */ - private function calculateAverageRating(Player $player, string $type, int $cut = 0): ?float + private function calculateAverageRating(Player $player, string $type, int $cut = 0): float { $pairings = $player->Pairings; $allratings = []; @@ -656,10 +753,11 @@ class Tournament * The average performance of the opponents * * @param Player $player + * @param string $type * @param int $cut - * @return float | null + * @return float */ - private function calculateAveragePerformance(Player $player, string $type, int $cut = 0): ?float + private function calculateAveragePerformance(Player $player, string $type, int $cut = 0): float { $pairings = $player->Pairings; $allratings = []; @@ -682,9 +780,9 @@ class Tournament * * @param Player $player * @param int $cut - * @return float | null + * @return float */ - private function calculateKoya(Player $player, int $cut = 50): ?float + private function calculateKoya(Player $player, int $cut = 50): float { $tiebreak = 0; foreach ($player->Pairings as $plkey => $plpairing) { @@ -705,9 +803,9 @@ class Tournament * @param Player $player * @param int $cutlowest * @param int $cuthighest - * @return float | null + * @return float */ - private function calculateBuchholz(Player $player, int $cutlowest = 0, int $cuthighest = 0): ?float + private function calculateBuchholz(Player $player, int $cutlowest = 0, int $cuthighest = 0): float { $tiebreak = 0; $intpairingsWithBye = $player->Pairings; @@ -750,9 +848,9 @@ class Tournament * The points of $player's opponents who $player won against, plus half of the points of $player's opponents who $player drew against * * @param Player $player - * @return float | null + * @return float */ - private function calculateSonneborn(Player $player): ?float + private function calculateSonneborn(Player $player): float { $tiebreak = 0; foreach ($player->Pairings as $key => $pairing) { @@ -773,9 +871,9 @@ class Tournament * * @param Player $player * @param int[] $points - * @return float | null + * @return float */ - private function calculateKashdan(Player $player, array $points): ?float + private function calculateKashdan(Player $player, array $points): float { $tiebreak = 0; foreach ($player->Pairings as $pairing) { @@ -800,9 +898,9 @@ class Tournament * Combined score of $player after each round * * @param Player $player - * @return float | null + * @return float */ - private function calculateCumulative(Player $player): ?float + private function calculateCumulative(Player $player): float { $tiebreak = 0; $score = []; @@ -846,11 +944,11 @@ class Tournament * Sets binary data that is read out the pairing file but is not needed immediately * * @param string $key - * @param bool|int|DateTime|string $Valueeyey + * @param bool|int|DateTime|string $value * @return void */ - public function __set(string $key, $Valueey): void + public function __set(string $key, $value): void { - $this->BinaryData[$key] = $Valueey; + $this->BinaryData[$key] = $value; } }