Merge branch 'task/phpdoc' into develop

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)

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/

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 $game
-     * @param Game $game2
      * @return bool
      */
     public function equals(Game $game): bool

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;
 }

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;
     }
 }

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 <schaak@jeroened.be>
  * @category    Main
@@ -39,19 +39,30 @@ use DateTime;
  */
 class Pairtwo6 implements ReaderInterface
 {
-    private const PT_DAYFACTOR = 32;
+    const PT_DAYFACTOR = 32;
-    private const PT_MONTHFACTOR = 16;
+    const PT_MONTHFACTOR = 16;
-    private const PT_YEARFACTOR = 512;
+    const PT_YEARFACTOR = 512;
-    private const PT_PASTOFFSET = 117;
+    const PT_PASTOFFSET = 117;
-    private const CompatibleVersions = ['6.', '5.'];
+    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

src/Readers/Swar4.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Reader Swar4
+ * Reader Swar-4
  *
  * Reads out Swar-4 files
  *
@@ -9,8 +9,6 @@
  * @package     Libpairtwo
  * @copyright   Copyright (c) 2018-2019 Jeroen De Meerleer <schaak@jeroened.be>
  */
-
-
 namespace JeroenED\Libpairtwo\Readers;
 
 use JeroenED\Libpairtwo\Enums\Color;
@@ -28,24 +26,42 @@ use JeroenED\Libpairtwo\Tournament;
 use DateTime;
 
 /**
- * Class Swar4
+ * Reader Swar4
- * @package JeroenED\Libpairtwo\Readers
+ *
+ * Reads out Swar-4 files
+ *
+ * @author      Jeroen De Meerleer <schaak@jeroened.be>
+ * @category    Main
+ * @package     Libpairtwo
+ * @copyright   Copyright (c) 2018-2019 Jeroen De Meerleer <schaak@jeroened.be>
  */
 class Swar4 implements ReaderInterface
 {
-    /** @var Tournament */
+    /**
-    public $Tournament;
+     * Version of Pairtwo this file was created with
-
+     *
-    /** @var string */
+     * @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) {

src/Round.php

@@ -55,7 +55,7 @@ class Round
      */
     public $Pairings = [];
 
-    /*
+    /**
      * Adds a game to the round
      *
      * @param Game $game

src/Tournament.php

@@ -1,8 +1,6 @@
 <?php
 /**
- * Class Tournament
+ * The file contains the Tournament class which takes care of almost every element in your tournament
- *
- * Class for the tournament from the pairing file
  *
  * @author      Jeroen De Meerleer <schaak@jeroened.be>
  * @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 int $key
-     * @param Player $b
      * @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;
     }
 }