From 783a12e7448a89abf2188bf1f87801073c15e222 Mon Sep 17 00:00:00 2001 From: Jens True Date: Mon, 26 Feb 2024 09:19:39 +0000 Subject: [PATCH] Bit of documentation effort --- README => README.md | 10 +++---- composer.json | 7 ++++- composer.lock | 48 ++++++++++++++++---------------- docs/index.rst | 52 +++++++++++++++++++++++++++++++++++ phpdoc.dist.xml => phpdoc.xml | 6 ++-- src/Rating.php | 7 ++++- 6 files changed, 96 insertions(+), 34 deletions(-) rename README => README.md (57%) create mode 100644 docs/index.rst rename phpdoc.dist.xml => phpdoc.xml (67%) diff --git a/README b/README.md similarity index 57% rename from README rename to README.md index 1ae7d27..7712971 100644 --- a/README +++ b/README.md @@ -1,3 +1,7 @@ +--- +title: README +... +# PHP TrueSkill Implementation This is a PHP port of the Moserware.Skills project that's available at http://github.com/moserware/Skills @@ -7,9 +11,3 @@ For more details on how the algorithm works, see http://www.moserware.com/2010/03/computing-your-skill.html For details on how to use this project, see the accompanying example snippets with this project. - -For development Composer and the following packages are used (Recommended as Phars installed via Phive) - -sudo phive install -g composer phpdocumentor infection phpcs phpcbf phploc phpbench overtrue/phplint -composer install -composer all \ No newline at end of file diff --git a/composer.json b/composer.json index 66587c0..3976e4b 100644 --- a/composer.json +++ b/composer.json @@ -38,12 +38,17 @@ ], "analyze-phpstan":"vendor/bin/phpstan analyze --error-format=raw", "analyze-psalm": "vendor/bin/psalm --no-cache", + "html": [ + "pandoc -s README.md -o output/README.html", + "pandoc -s docs/index.rst -o output/index.html" + ], "all": [ "@test", "@document", "@benchmark", "@lint", - "@static" + "@static", + "@html" ] } } diff --git a/composer.lock b/composer.lock index 8b48f2c..05c3958 100644 --- a/composer.lock +++ b/composer.lock @@ -1099,21 +1099,21 @@ }, { "name": "phpdocumentor/type-resolver", - "version": "1.8.1", + "version": "1.8.2", "source": { "type": "git", "url": "https://github.com/phpDocumentor/TypeResolver.git", - "reference": "bc3dc91a5e9b14aa06d1d9e90647c5c5a2cc5353" + "reference": "153ae662783729388a584b4361f2545e4d841e3c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phpDocumentor/TypeResolver/zipball/bc3dc91a5e9b14aa06d1d9e90647c5c5a2cc5353", - "reference": "bc3dc91a5e9b14aa06d1d9e90647c5c5a2cc5353", + "url": "https://api.github.com/repos/phpDocumentor/TypeResolver/zipball/153ae662783729388a584b4361f2545e4d841e3c", + "reference": "153ae662783729388a584b4361f2545e4d841e3c", "shasum": "" }, "require": { "doctrine/deprecations": "^1.0", - "php": "^7.4 || ^8.0", + "php": "^7.3 || ^8.0", "phpdocumentor/reflection-common": "^2.0", "phpstan/phpdoc-parser": "^1.13" }, @@ -1151,9 +1151,9 @@ "description": "A PSR-5 based resolver of Class names, Types and Structural Element Names", "support": { "issues": "https://github.com/phpDocumentor/TypeResolver/issues", - "source": "https://github.com/phpDocumentor/TypeResolver/tree/1.8.1" + "source": "https://github.com/phpDocumentor/TypeResolver/tree/1.8.2" }, - "time": "2024-01-18T19:15:27+00:00" + "time": "2024-02-23T11:10:43+00:00" }, { "name": "phpmetrics/phpmetrics", @@ -1233,16 +1233,16 @@ }, { "name": "phpstan/phpdoc-parser", - "version": "1.25.0", + "version": "1.26.0", "source": { "type": "git", "url": "https://github.com/phpstan/phpdoc-parser.git", - "reference": "bd84b629c8de41aa2ae82c067c955e06f1b00240" + "reference": "231e3186624c03d7e7c890ec662b81e6b0405227" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phpstan/phpdoc-parser/zipball/bd84b629c8de41aa2ae82c067c955e06f1b00240", - "reference": "bd84b629c8de41aa2ae82c067c955e06f1b00240", + "url": "https://api.github.com/repos/phpstan/phpdoc-parser/zipball/231e3186624c03d7e7c890ec662b81e6b0405227", + "reference": "231e3186624c03d7e7c890ec662b81e6b0405227", "shasum": "" }, "require": { @@ -1274,9 +1274,9 @@ "description": "PHPDoc parser with support for nullable, intersection and generic types", "support": { "issues": "https://github.com/phpstan/phpdoc-parser/issues", - "source": "https://github.com/phpstan/phpdoc-parser/tree/1.25.0" + "source": "https://github.com/phpstan/phpdoc-parser/tree/1.26.0" }, - "time": "2024-01-04T17:06:16+00:00" + "time": "2024-02-23T16:05:55+00:00" }, { "name": "phpstan/phpstan", @@ -1663,16 +1663,16 @@ }, { "name": "phpunit/phpunit", - "version": "10.5.10", + "version": "10.5.11", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "50b8e314b6d0dd06521dc31d1abffa73f25f850c" + "reference": "0d968f6323deb3dbfeba5bfd4929b9415eb7a9a4" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/50b8e314b6d0dd06521dc31d1abffa73f25f850c", - "reference": "50b8e314b6d0dd06521dc31d1abffa73f25f850c", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/0d968f6323deb3dbfeba5bfd4929b9415eb7a9a4", + "reference": "0d968f6323deb3dbfeba5bfd4929b9415eb7a9a4", "shasum": "" }, "require": { @@ -1744,7 +1744,7 @@ "support": { "issues": "https://github.com/sebastianbergmann/phpunit/issues", "security": "https://github.com/sebastianbergmann/phpunit/security/policy", - "source": "https://github.com/sebastianbergmann/phpunit/tree/10.5.10" + "source": "https://github.com/sebastianbergmann/phpunit/tree/10.5.11" }, "funding": [ { @@ -1760,7 +1760,7 @@ "type": "tidelift" } ], - "time": "2024-02-04T09:07:51+00:00" + "time": "2024-02-25T14:05:00+00:00" }, { "name": "psalm/plugin-phpunit", @@ -3653,16 +3653,16 @@ }, { "name": "vimeo/psalm", - "version": "5.22.1", + "version": "5.22.2", "source": { "type": "git", "url": "https://github.com/vimeo/psalm.git", - "reference": "e9dad66e11274315dac27e08349c628c7d6a1a43" + "reference": "d768d914152dbbf3486c36398802f74e80cfde48" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/vimeo/psalm/zipball/e9dad66e11274315dac27e08349c628c7d6a1a43", - "reference": "e9dad66e11274315dac27e08349c628c7d6a1a43", + "url": "https://api.github.com/repos/vimeo/psalm/zipball/d768d914152dbbf3486c36398802f74e80cfde48", + "reference": "d768d914152dbbf3486c36398802f74e80cfde48", "shasum": "" }, "require": { @@ -3759,7 +3759,7 @@ "issues": "https://github.com/vimeo/psalm/issues", "source": "https://github.com/vimeo/psalm" }, - "time": "2024-02-15T22:52:31+00:00" + "time": "2024-02-22T23:39:07+00:00" }, { "name": "webmozart/assert", diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..fc09db3 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,52 @@ +Documentation +============= +This is a PHP port of the Moserware.Skills project that's available at + +http://github.com/moserware/Skills + +For more details on how the algorithm works, see + +http://www.moserware.com/2010/03/computing-your-skill.html + +For details on how to use this project, see the accompanying example snippets with this project. + +https://www.microsoft.com/en-us/research/project/trueskill-ranking-system/ +https://github.com/moserware/PHPSkills +https://www.moserware.com/2010/03/computing-your-skill.html + + +From Microsoft +-------------- +The TrueSkill ranking system is a skill based ranking system for Xbox Live(opens in new tab) developed at Microsoft Research(opens in new tab). The purpose of a ranking system is to both identify and track the skills of gamers in a game (mode) in order to be able to match them into competitive matches. TrueSkill has been used to rank and match players in many different games, from Halo 3 to Forza Motorsport 7(opens in new tab). + +An improved version of the TrueSkill ranking system, named TrueSkill 2(opens in new tab), launched with Gears of War 4(opens in new tab) and was later incorporated into Halo 5(opens in new tab). + +The classic TrueSkill ranking system only uses the final standings of all teams in a match in order to update the skill estimates (ranks) of all players in the match. The TrueSkill 2 ranking system also uses the individual scores of players in order to weight the contribution of each player to each team. As a result, TrueSkill 2 is much faster at figuring out the skill of a new player. + + +Links +----- + +* `Project README `_ +* `API Documentations `_ +* `CodeCoverage `_ +* `Metrics `_ +* `Test report `_ +* `Mutation testing `_ + + +Standard Tools +-------------- +* PHP8.3 +* PlantUML +* GraphViz +* Pandoc + + +PHP Tools +--------- +For development Composer and the following packages are used (Recommended as Phars installed via Phive) + +* sudo phive install -g composer phpdocumentor infection phpcs phpcbf phploc phpbench overtrue/phplint +* composer install +* composer all \ No newline at end of file diff --git a/phpdoc.dist.xml b/phpdoc.xml similarity index 67% rename from phpdoc.dist.xml rename to phpdoc.xml index 991c33e..11555de 100644 --- a/phpdoc.dist.xml +++ b/phpdoc.xml @@ -3,16 +3,18 @@ configVersion="3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://www.phpdoc.org" + xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd" > - backupscript + trueskill output/docs - + src + \ No newline at end of file diff --git a/src/Rating.php b/src/Rating.php index b599b71..c0c1187 100644 --- a/src/Rating.php +++ b/src/Rating.php @@ -4,9 +4,11 @@ declare(strict_types=1); namespace DNW\Skills; -// Container for a player's rating. use DNW\Skills\Numerics\GaussianDistribution; +/** + * Container for a player's rating. + */ class Rating implements \Stringable { private const CONSERVATIVE_STANDARD_DEVIATION_MULTIPLIER = 3; @@ -46,6 +48,9 @@ class Rating implements \Stringable return $this->mean - $this->conservativeStandardDeviationMultiplier * $this->standardDeviation; } + /** + * Get a partial rating update. + */ public function getPartialUpdate(Rating $prior, Rating $fullPosterior, float $updatePercentage): Rating { $priorGaussian = new GaussianDistribution($prior->getMean(), $prior->getStandardDeviation());