Implemented phpdox to be able to generate some internal documentation…

…. Decided it would be easier to follow if each class at least had a one-liner description.
howardjones · Jan 7, 2018 · fb18c82 · fb18c82
1 parent c6c8066
commit fb18c82
Show file tree

Hide file tree

Showing 91 changed files with 509 additions and 172 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,6 +12,7 @@ composer.lock
 !build/network-weathermap.doxy
 vendor/*
 dev/generated/
+dev/docs/
 dev/phpcs/
 dev/vagrant-testers/*.zip
 node_modules/

diff --git a/composer.json b/composer.json
@@ -27,7 +27,8 @@
     "phpunit/php-code-coverage": "~4",
     "jakub-onderka/php-parallel-lint": "^0.9.2",
     "johnkary/phpunit-speedtrap": "^1.1",
-    "lstrojny/phpunit-clever-and-smart": "^0.5.0"
+    "lstrojny/phpunit-clever-and-smart": "^0.5.0",
+    "phploc/phploc": "^4.0"
   },
   "autoload": {
     "psr-4": {"Weathermap\\": "lib/Weathermap"}

diff --git a/lib/Weathermap/CLI/MapProcessor.php b/lib/Weathermap/CLI/MapProcessor.php
@@ -8,6 +8,9 @@
 use Weathermap\Core\Map;
 use Weathermap\Core\MapUtility;
 
+/**
+ * A base class for various command-line tools that take in a map config file, process it, and spit out a new one.
+ */
 class MapProcessor
 {
     /** @var GetOpt $getOpt */

diff --git a/lib/Weathermap/CLI/Runner.php b/lib/Weathermap/CLI/Runner.php
@@ -8,6 +8,11 @@
 use Weathermap\Core\Map;
 use Weathermap\Core\MapUtility;
 
+/**
+ * The CLI map-creation tool
+ *
+ * @package Weathermap\CLI
+ */
 class Runner
 {
     /** @var GetOpt $getOpt */

diff --git a/lib/Weathermap/Core/AngledLinkGeometry.php b/lib/Weathermap/Core/AngledLinkGeometry.php
@@ -2,6 +2,11 @@
 
 namespace Weathermap\Core;
 
+/**
+ * All the parts of LinkGeometry that are specific to angled links
+ *
+ * @package Weathermap\Core
+ */
 class AngledLinkGeometry extends LinkGeometry
 {
 

diff --git a/lib/Weathermap/Core/App.php b/lib/Weathermap/Core/App.php
@@ -1,14 +1,8 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 18:27
- */
 
 namespace Weathermap\Core;
 
-// XXX - unused
+/** XXX - unused */
 
 class App
 {

diff --git a/lib/Weathermap/Core/BoundingBox.php b/lib/Weathermap/Core/BoundingBox.php
@@ -1,6 +1,11 @@
 <?php
 namespace Weathermap\Core;
 
+/**
+ * Given a series of points or rectangles, keep track of the minimum-sized rectangle that will contain them.
+ *
+ * @package Weathermap\Core
+ */
 class BoundingBox
 {
     private $minimumX;

diff --git a/lib/Weathermap/Core/CatmullRom1D.php b/lib/Weathermap/Core/CatmullRom1D.php
@@ -2,7 +2,10 @@
 
 namespace Weathermap\Core;
 
-// Given 4 ordinates and a parameter from 0 to 1, calculate a point on the Catmull Rom spline through them.
+/**
+ * Given 4 ordinates and a parameter from 0 to 1, calculate a point on the Catmull-Rom spline through them.
+ */
+
 class CatmullRom1D
 {
     private $aParam;
@@ -18,6 +21,12 @@ public function __construct($point0, $point1, $point2, $point3)
         $this->dParam = 2 * $point1;
     }
 
+    /**
+     * Calculate the ordinate given the parameter (t)
+     *
+     * @param float $parameter
+     * @return float
+     */
     public function calculate($parameter)
     {
         $parameterSquared = $parameter * $parameter;

diff --git a/lib/Weathermap/Core/ConfigItem.php b/lib/Weathermap/Core/ConfigItem.php
@@ -2,7 +2,7 @@
 
 namespace Weathermap\Core;
 
-// XXX - unused
+/** XXX - unused */
 
 class ConfigItem
 {

diff --git a/lib/Weathermap/Core/ConfigReader.php b/lib/Weathermap/Core/ConfigReader.php
@@ -2,16 +2,12 @@
 
 namespace Weathermap\Core;
 
-/*
- * Refactoring of all the ReadConfig code out of the giant Weathermap class
- *
+/**
  * A ConfigReader holds state for parsing through a config file. Includes are done by
  * creating a new ConfigReader and passing it the state of the current one. Shared state
  * reduces the amount of junk passed to HANDLE_* functions.
  *
  */
-
-
 class ConfigReader
 {
     private $lineCount = 0;

diff --git a/lib/Weathermap/Core/CurvedLinkGeometry.php b/lib/Weathermap/Core/CurvedLinkGeometry.php
@@ -1,6 +1,11 @@
 <?php
 namespace Weathermap\Core;
 
+/**
+ * All the parts of LinkGeometry that are specific to curved links
+ *
+ * @package Weathermap\Core
+ */
 class CurvedLinkGeometry extends LinkGeometry
 {
     protected function calculateSpine($pointsPerSpan = 32)

diff --git a/lib/Weathermap/Core/Font.php b/lib/Weathermap/Core/Font.php
@@ -2,6 +2,10 @@
 
 namespace Weathermap\Core;
 
+/**
+ * Base class for a font in the FontTable
+ * @package Weathermap\Core
+ */
 class Font
 {
     public $type;

diff --git a/lib/Weathermap/Core/FontTable.php b/lib/Weathermap/Core/FontTable.php
@@ -1,13 +1,12 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 11:12
- */
 
 namespace Weathermap\Core;
 
+/**
+ * A manager for loading fonts, and also producing their config for getConfig()
+ *
+ * @package Weathermap\Core
+ */
 class FontTable
 {
     /** @var Font[] $table  */

diff --git a/lib/Weathermap/Core/GDFont.php b/lib/Weathermap/Core/GDFont.php
@@ -1,13 +1,12 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 11:12
- */
 
 namespace Weathermap\Core;
 
+/**
+ * FontTable member representing a GD format bitmap font
+ *
+ * @package Weathermap\Core
+ */
 class GDFont extends Font
 {
     public $gdnumber;

diff --git a/lib/Weathermap/Core/HTMLImagemap.php b/lib/Weathermap/Core/HTMLImagemap.php
@@ -17,6 +17,11 @@
 
 use Weathermap\Core\HTMLImagemapArea;
 
+/**
+ * The base class that contains the ImagemapArea objects, and produces the map HTML. (UNUSED?)
+ *
+ * @package Weathermap\Core
+ */
 class HTMLImagemap
 {
     /** @var HTMLImagemapArea[] $shapes */

diff --git a/lib/Weathermap/Core/HTMLImagemapArea.php b/lib/Weathermap/Core/HTMLImagemapArea.php
@@ -1,13 +1,11 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 11:14
- */
 
 namespace Weathermap\Core;
 
+/**
+ * Base class for the other ImagemapArea classes - just the common stuff
+ * @package Weathermap\Core
+ */
 class HTMLImagemapArea
 {
     public $href;

diff --git a/lib/Weathermap/Core/HTMLImagemapAreaCircle.php b/lib/Weathermap/Core/HTMLImagemapAreaCircle.php
@@ -1,13 +1,11 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 11:15
- */
 
 namespace Weathermap\Core;
 
+/**
+ * A circle for HTMLImagemap (not used by Weathermap)
+ * @package Weathermap\Core
+ */
 class HTMLImagemapAreaCircle extends HTMLImagemapArea
 {
     public $centx;

diff --git a/lib/Weathermap/Core/HTMLImagemapAreaPolygon.php b/lib/Weathermap/Core/HTMLImagemapAreaPolygon.php
@@ -1,13 +1,12 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 11:14
- */
 
 namespace Weathermap\Core;
 
+/**
+ * A polygon for HTMLImagemap (used for link arrows)
+ *
+ * @package Weathermap\Core
+ */
 class HTMLImagemapAreaPolygon extends HTMLImagemapArea
 {
     public $points = array();

diff --git a/lib/Weathermap/Core/HTMLImagemapAreaRectangle.php b/lib/Weathermap/Core/HTMLImagemapAreaRectangle.php
@@ -1,13 +1,12 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 11:14
- */
 
 namespace Weathermap\Core;
 
+/**
+ * A rectangle for HTMLImagemap
+ *
+ * @package Weathermap\Core
+ */
 class HTMLImagemapAreaRectangle extends HTMLImagemapArea
 {
     public $x1;

diff --git a/lib/Weathermap/Core/ImageLoader.php b/lib/Weathermap/Core/ImageLoader.php
@@ -1,6 +1,13 @@
 <?php
 namespace Weathermap\Core;
 
+/**
+ * A handler for loading images required by the map (e.g. backgrounds and icons). It also
+ * is responsible for any colorizing and resizing necessary. It maintains a cache, to try and speed up
+ * maps with many resized icons, in particular.
+ *
+ * @package Weathermap\Core
+ */
 class ImageLoader
 {
     private $cache = array();

diff --git a/lib/Weathermap/Core/ImageUtility.php b/lib/Weathermap/Core/ImageUtility.php
@@ -2,6 +2,11 @@
 
 namespace Weathermap\Core;
 
+/**
+ * Utility functions related to manipulating GD images
+ *
+ * @package Weathermap\Core
+ */
 class ImageUtility
 {
     /**

diff --git a/lib/Weathermap/Core/Legend.php b/lib/Weathermap/Core/Legend.php
@@ -4,6 +4,11 @@
 
 use Weathermap\Core\MapScale;
 
+/**
+ * The in-map display of a scale
+ *
+ * @package Weathermap\Core
+ */
 class Legend extends MapItem
 {
     /** @var MapScale $scale */

diff --git a/lib/Weathermap/Core/LineSegment.php b/lib/Weathermap/Core/LineSegment.php
@@ -1,13 +1,11 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: howie
- * Date: 23/09/17
- * Time: 11:16
- */
 
 namespace Weathermap\Core;
 
+/**
+ * A LineSegment is a Line that only exists between two points (UNUSED?)
+ * @package Weathermap\Core
+ */
 class LineSegment
 {
     public $point1;

diff --git a/lib/Weathermap/Core/LinkGeometry.php b/lib/Weathermap/Core/LinkGeometry.php
@@ -2,8 +2,8 @@
 
 namespace Weathermap\Core;
 
-/***
- * Class WMLinkGeometry - everything needed to draw a link
+/**
+ * everything needed to draw a link
  *
  * Actually collect all the link-drawing code into an object!
  *

diff --git a/lib/Weathermap/Core/LinkGeometryFactory.php b/lib/Weathermap/Core/LinkGeometryFactory.php
@@ -1,6 +1,11 @@
 <?php
 namespace Weathermap\Core;
 
+/**
+ * Given the link style, return an appropriate LinkGeometry object to draw it
+ *
+ * @package Weathermap\Core
+ */
 class LinkGeometryFactory
 {
     /**