Improve documentation

Account/Account.php

@@ -487,7 +487,7 @@ class Account implements ArrayableInterface, \JsonSerializable
      *
      * @return void
      *
-     * @throws InvalidEnumValue
+     * @throws InvalidEnumValue This exception is thrown if a invalid status is used
      *
      * @since  1.0.0
      */
@@ -521,7 +521,7 @@ class Account implements ArrayableInterface, \JsonSerializable
      *
      * @return void
      *
-     * @throws InvalidEnumValue
+     * @throws InvalidEnumValue This exception is thrown if an invalid type is used
      *
      * @since  1.0.0
      */
@@ -640,11 +640,7 @@ class Account implements ArrayableInterface, \JsonSerializable
     }
 
     /**
-     * Json serialize.
+     * {@inheritdoc}
-     *
-     * @return array<string, mixed>
-     *
-     * @since  1.0.0
      */
     public function jsonSerialize()
     {

Account/AccountManager.php

@@ -20,7 +20,7 @@ use phpOMS\DataStorage\Session\SessionInterface;
 /**
  * Account manager class.
  *
- * The account manager is used to manage multiple accounts.
+ * The account manager is used to manage accounts.
  *
  * @package    phpOMS\Account
  * @license    OMS License 1.0

Account/Group.php

@@ -167,7 +167,7 @@ class Group implements ArrayableInterface, \JsonSerializable
      *
      * @return void
      *
-     * @throws InvalidEnumValue
+     * @throws InvalidEnumValue This exception is thrown if an invalid status is used
      *
      * @since  1.0.0
      */

Account/GroupStatus.php

@@ -17,7 +17,7 @@ namespace phpOMS\Account;
 use phpOMS\Stdlib\Base\Enum;
 
 /**
- * Accept status enum.
+ * Group status enum.
  *
  * @package    phpOMS\Account
  * @license    OMS License 1.0

Account/PermissionOwner.php

@@ -17,7 +17,7 @@ namespace phpOMS\Account;
 use phpOMS\Stdlib\Base\Enum;
 
 /**
- * Permision state enum.
+ * Permision type/owner enum.
  *
  * @package    phpOMS\Account
  * @license    OMS License 1.0

Asset/AssetManager.php

@@ -33,15 +33,6 @@ final class AssetManager implements \Countable
      */
     private $assets = [];
 
-    /**
-     * Constructor.
-     *
-     * @since  1.0.0
-     */
-    public function __construct()
-    {
-    }
-
     /**
      * Add asset.
      *

Business/Marketing/NetPromoterScore.php

@@ -52,7 +52,12 @@ final class NetPromoterScore
     /**
      * Get total NPS.
      *
-     * @return int
+     * Values of > 0 are considered good and above 50 is considered excellent.
+     * Remark: Amazon had a NPS of 69 in NA in 2016
+     *
+     * @latex NPS = Promoters - Detractors
+     *
+     * @return int Retunrs the NPS
      *
      * @since  1.0.0
      */

Business/Programming/Metrics.php

@@ -35,7 +35,7 @@ final class Metrics
      * @param int $b Branches
      * @param int $c Conditionals
      *
-     * @return int
+     * @return int ABC metric score
      *
      * @since  1.0.0
      */
@@ -52,7 +52,7 @@ final class Metrics
      * @param int   $complexity Complexity
      * @param float $coverage   Coverage
      *
-     * @return int
+     * @return int CRAP score
      *
      * @since  1.0.0
      *

Config/OptionsTrait.php

@@ -17,6 +17,8 @@ namespace phpOMS\Config;
 /**
  * Options trait.
  *
+ * This trait basically implements the OptionsInterface
+ *
  * @package    phpOMS\Config
  * @license    OMS License 1.0
  * @link       http://website.orange-management.de

Contract/ArrayableInterface.php

@@ -15,9 +15,9 @@ declare(strict_types=1);
 namespace phpOMS\Contract;
 
 /**
- * Defines an object arrayable.
+ * This interface forces classes to implement an array representation of themselves.
  *
- * This stands always in combination with a jsonable instance.
+ * This can be helpful for \JsonSerializable classes or classes which need to be represented as array.
  *
  * @package    phpOMS\Contract
  * @license    OMS License 1.0

Contract/RenderableInterface.php

@@ -18,7 +18,7 @@ namespace phpOMS\Contract;
  * Make a class renderable.
  *
  * This is primarily used for classes that provide formatted output or output,
- * that get's rendered in third party applications.
+ * that get rendered.
  *
  * @package    phpOMS\Contract
  * @license    OMS License 1.0

DataStorage/Cache/CachePool.php

@@ -22,8 +22,7 @@ use phpOMS\DataStorage\DataStoragePoolInterface;
 /**
  * Cache class.
  *
- * Responsible for caching scalar data types and arrays.
+ * Responsible for storing cache implementation.
- * Caching HTML output and objects coming soon/is planned.
  *
  * @package    phpOMS\DataStorage\Cache
  * @license    OMS License 1.0
@@ -40,15 +39,6 @@ final class CachePool implements DataStoragePoolInterface
      */
     private $pool = null;
 
-    /**
-     * Constructor.
-     *
-     * @since  1.0.0
-     */
-    public function __construct()
-    {
-    }
-
     /**
      * Add database.
      *

DataStorage/Cache/Connection/CacheValueType.php

@@ -31,9 +31,9 @@ abstract class CacheValueType extends Enum
     public const _INT              = 0; /* Data is integer */
     public const _STRING           = 1; /* Data is string */
     public const _ARRAY            = 2; /* Data is array */
-    public const _SERIALIZABLE     = 3; /* Data is object */
+    public const _SERIALIZABLE     = 3; /* Data implements \Serializable */
     public const _FLOAT            = 4; /* Data is float */
     public const _BOOL             = 5; /* Data is bool */
-    public const _JSONSERIALIZABLE = 6;
+    public const _JSONSERIALIZABLE = 6; /* Data implements \JsonSerializable */
-    public const _NULL             = 7;
+    public const _NULL             = 7; /* Data is null */
 }

DataStorage/Cache/Connection/ConnectionAbstract.php

@@ -152,7 +152,9 @@ abstract class ConnectionAbstract implements ConnectionInterface
     }
 
     /**
-     * {@inheritdoc}
+     * Closes the chache.
+     *
+     * @since  1.0.0
      */
     public function close() : void
     {

DataStorage/Cache/Connection/ConnectionFactory.php

@@ -40,8 +40,6 @@ class ConnectionFactory
     /**
      * Create cache connection.
      *
-     * Overwrites current connection if existing
-     *
      * @param string[] $cacheData the basic cache information for establishing a connection
      *
      * @return ConnectionInterface

DataStorage/Cache/Connection/FileCache.php

@@ -22,9 +22,18 @@ use phpOMS\System\File\Local\Directory;
 use phpOMS\System\File\Local\File;
 
 /**
- * MemCache class.
+ * File cache.
  *
- * PHP Version 7.2
+ * This implementation uses the hard drive as cache by saving data to the disc as text files.
+ * The text files follow a defined strucuture which allows this implementation to parse the cached data.
+ *
+ * Allowed datatypes: null, int, bool, float, string, \DateTime, \JsonSerializable, \Serializable
+ * File structure:
+ *      data type (1 byte)
+ *      delimiter (1 byte)
+ *      expiration duration in seconds (1 - n bytes) (based on the file creation date)
+ *      delimiter (1 byte)
+ *      data (n bytes)
  *
  * @package    phpOMS\DataStorage\Cache\Connection
  * @license    OMS License 1.0
@@ -190,7 +199,9 @@ class FileCache extends ConnectionAbstract
      *
      * @param mixed $value Data to cache
      *
-     * @return int
+     * @return int Returns the cache type for a value
+     * 
+     * @throws \InvalidArgumentException This exception is thrown if an unsupported datatype is used
      *
      * @since  1.0.0
      */
@@ -225,7 +236,7 @@ class FileCache extends ConnectionAbstract
      *
      * @return string
      *
-     * @throws InvalidEnumValue
+     * @throws InvalidEnumValue This exception is thrown if an unsupported cache value type is used
      *
      * @since  1.0.0
      */

DataStorage/Cache/Connection/RedisCache.php

@@ -21,8 +21,6 @@ use phpOMS\DataStorage\Cache\Exception\InvalidConnectionConfigException;
 /**
  * RedisCache class.
  *
- * PHP Version 5.6
- *
  * @package    phpOMS\DataStorage\Cache\Connection
  * @license    OMS License 1.0
  * @link       http://website.orange-management.de

DataStorage/Cache/Exception/InvalidConnectionConfigException.php

@@ -15,7 +15,7 @@ declare(strict_types=1);
 namespace phpOMS\DataStorage\Cache\Exception;
 
 /**
- * Permission exception class.
+ * Invalid cache config exception class.
  *
  * @package    phpOMS\DataStorage\Cache\Exception
  * @license    OMS License 1.0
@@ -35,6 +35,6 @@ final class InvalidConnectionConfigException extends \InvalidArgumentException
      */
     public function __construct(string $message = '', int $code = 0, \Exception $previous = null)
     {
-        parent::__construct('Missing config value for "' . $message . '".', $code, $previous);
+        parent::__construct('Invalid/missing config value for "' . $message . '".', $code, $previous);
     }
 }

DataStorage/Cookie/CookieJar.php

@@ -118,7 +118,7 @@ final class CookieJar
      *
      * @return bool
      *
-     * @throws LockException
+     * @throws LockException Throws this exception if the cookie is already sent
      *
      * @since  1.0.0
      */
@@ -166,7 +166,7 @@ final class CookieJar
      *
      * @return void
      *
-     * @throws LockException
+     * @throws LockException Throws this exception if the cookie is already sent
      *
      * @since  1.0.0
      */

DataStorage/DataMapperInterface.php

@@ -19,7 +19,7 @@ use phpOMS\DataStorage\Database\Query\Builder;
 /**
  * Datamapper interface.
  *
- * DB, Cache, Session
+ * This interface is used for DB, Cache & Session implementations
  *
  * @package    phpOMS\DataStorage
  * @license    OMS License 1.0

DataStorage/Database/DataMapperAbstract.php

@@ -603,7 +603,7 @@ class DataMapperAbstract implements DataMapperInterface
      *
      * @return void
      *
-     * @throws InvalidMapperException
+     * @throws InvalidMapperException Throws this exception if the mapper in the has many relation is invalid
      *
      * @since  1.0.0
      */
@@ -689,7 +689,7 @@ class DataMapperAbstract implements DataMapperInterface
      *
      * @return void
      *
-     * @throws InvalidMapperException
+     * @throws InvalidMapperException Throws this exception if the mapper in the has many relation is invalid
      *
      * @since  1.0.0
      */
@@ -933,7 +933,7 @@ class DataMapperAbstract implements DataMapperInterface
      *
      * @return void
      *
-     * @throws InvalidMapperException
+     * @throws InvalidMapperException Throws this exception if the mapper in the has many relation is invalid
      *
      * @since  1.0.0
      */
@@ -1020,7 +1020,7 @@ class DataMapperAbstract implements DataMapperInterface
      *
      * @return void
      *
-     * @throws InvalidMapperException
+     * @throws InvalidMapperException Throws this exception if the mapper in the has many relation is invalid
      *
      * @since  1.0.0
      */
@@ -1455,7 +1455,7 @@ class DataMapperAbstract implements DataMapperInterface
      *
      * @return void
      *
-     * @throws InvalidMapperException
+     * @throws InvalidMapperException Throws this exception if the mapper in the has many relation is invalid
      *
      * @since  1.0.0
      */

DataStorage/LockException.php

@@ -15,7 +15,10 @@ declare(strict_types=1);
 namespace phpOMS\DataStorage;
 
 /**
- * Permission exception class.
+ * Lock exception class.
+ *
+ * This exception is used for instances that have a lock componenent/state after which rendering,
+ * header manipulation etc. are no longer allowed/possible.
  *
  * @package    phpOMS\DataStorage
  * @license    OMS License 1.0

Dispatcher/Dispatcher.php

@@ -14,6 +14,7 @@ declare(strict_types=1);
 
 namespace phpOMS\Dispatcher;
 
+use phpOMS\Autoloader;
 use phpOMS\ApplicationAbstract;
 use phpOMS\Module\ModuleAbstract;
 use phpOMS\System\File\PathException;
@@ -62,10 +63,12 @@ final class Dispatcher
     /**
      * Dispatch controller.
      *
-     * @param array|\Closure|string $controller Controller string
+     * @param array|\Closure|string $controller Controller
      * @param null|array|mixed      ...$data    Data
      *
-     * @return array
+     * @return array Returns array of all dispatched results
+     *
+     * @throws \UnexpectedValueException This exception is thrown for unsupported controller representations
      *
      * @since  1.0.0
      */
@@ -93,11 +96,22 @@ final class Dispatcher
     /**
      * Dispatch string.
      *
+     * The disptacher can dispatch static functions.
+     * String: `some/namespace/path::myStaticFunction`
+     *
+     * Additionally it's also possible to dispatch functions of modules.
+     * Modules are classes which can get instantiated with `new Class(ApplicationAbstract $app)`
+     * String: `some/namespace/path:myMethod`
+     *
      * @param string     $controller Controller string
      * @param null|array $data       Data
      *
      * @return array
      *
+     * @throws PathException             This exception is thrown if the function cannot be autoloaded.
+     * @throws \Exception                This exception is thrown if the function is not callable.
+     * @throws \UnexpectedValueException This exception is thrown if the controller string is malformed.
+     *
      * @since  1.0.0
      */
     private function dispatchString(string $controller, array $data = null) : array
@@ -105,8 +119,8 @@ final class Dispatcher
         $views    = [];
         $dispatch = \explode(':', $controller);
 
-        if (!\file_exists($path = __DIR__ . '/../../' . \ltrim(\str_replace('\\', '/', $dispatch[0]), '/') . '.php')) {
+        if (!Autoloader::exists($dispatch[0])) {
-            throw new PathException($path);
+            throw new PathException($dispatch[0]);
         }
 
         if (($c = \count($dispatch)) === 3) {

Event/EventManager.php

@@ -19,14 +19,18 @@ use phpOMS\Dispatcher\Dispatcher;
 /**
  * EventManager class.
  *
+ * The event manager allows to define events which can be triggered/executed in an application.
+ * This implementation allows to create sub-conditions which need to be met (triggered in advance) bevore the actual
+ * callback is getting executed.
+ *
+ * What happens after triggering an event (removing the callback, resetting the sub-conditions etc.) depends on the setup.
+ *
  * @package    phpOMS\Event
  * @license    OMS License 1.0
  * @link       http://website.orange-management.de
  * @since      1.0.0
- *
- * @todo       : make cachable + database storable -> can reload user defined listeners (persistent events)
  */
-final class EventManager
+final class EventManager implements \Countable
 {
     /**
      * Events.
@@ -55,7 +59,7 @@ final class EventManager
     /**
      * Constructor.
      *
-     * @param Dispatcher $dispatcher Dispatcher
+     * @param Dispatcher $dispatcher Dispatcher. If no dispatcher is provided a simple general purpose dispatcher is used.
      *
      * @since  1.0.0
      */
@@ -305,11 +309,7 @@ final class EventManager
     }
 
     /**
-     * Count events.
+     * {@inheritdoc}
-     *
-     * @return int
-     *
-     * @since  1.0.0
      */
     public function count() : int
     {

Localization/Localization.php

@@ -144,6 +144,8 @@ final class Localization
      *
      * @return void
      *
+     * @throws InvalidEnumValue This exception is thrown if the language is invalid
+     *
      * @since  1.0.0
      */
     public function loadFromLanguage(string $langCode) : void
@@ -224,6 +226,8 @@ final class Localization
      *
      * @return void
      *
+     * @throws InvalidEnumValue This exception is thrown if the country is invalid
+     *
      * @since  1.0.0
      */
     public function setCountry(string $country) : void
@@ -254,6 +258,8 @@ final class Localization
      *
      * @return void
      *
+     * @throws InvalidEnumValue This exception is thrown if the timezone is invalid
+     *
      * @since  1.0.0
      */
     public function setTimezone(string $timezone) : void
@@ -284,7 +290,7 @@ final class Localization
      *
      * @return void
      *
-     * @throws InvalidEnumValue
+     * @throws InvalidEnumValue This exception is thrown if the language is invalid
      *
      * @since  1.0.0
      */
@@ -318,6 +324,8 @@ final class Localization
      *
      * @return void
      *
+     * @throws InvalidEnumValue This exception is thrown if the currency is invalid
+     *
      * @since  1.0.0
      */
     public function setCurrency(string $currency) : void

Localization/Money.php

@@ -102,6 +102,8 @@ final class Money implements \Serializable
      *
      * @return int
      *
+     * @throws \Exception
+     *
      * @since  1.0.0
      */
     public static function toInt(string $value, string $thousands = ',', string $decimal = '.')  : int
@@ -187,6 +189,8 @@ final class Money implements \Serializable
      *
      * @return string
      *
+     * @throws \Exception
+     *
      * @since  1.0.0
      */
     public function getAmount(int $decimals = 2) : string

Math/Number/Integer.php

@@ -149,7 +149,7 @@ final class Integer
      *
      * @return array<int>
      *
-     * @throws \Exception
+     * @throws \Exception This exception is thrown if the value is not odd
      *
      * @since  1.0.0
      */

Math/Statistic/Average.php

@@ -168,7 +168,7 @@ final class Average
      *
      * @return float
      *
-     * @throws ZeroDevisionException
+     * @throws ZeroDevisionException This exception is thrown if the values array is empty
      *
      * @since  1.0.0
      */
@@ -240,7 +240,7 @@ final class Average
      *
      * @return float
      *
-     * @throws \Exception
+     * @throws ZeroDevisionException This exception is thrown if the values array is empty
      *
      * @since  1.0.0
      */
@@ -265,7 +265,7 @@ final class Average
      *
      * @return float
      *
-     * @throws \Exception
+     * @throws ZeroDevisionException This exception is thrown if a value in the values array is 0 or if the values array is empty
      *
      * @since  1.0.0
      */
@@ -280,6 +280,10 @@ final class Average
         $count = \count($values);
         $sum   = 0.0;
 
+        if ($count === 0) {
+            throw new ZeroDevisionException();
+        }
+
         foreach ($values as $value) {
             if ($value === 0) {
                 throw new ZeroDevisionException();

Math/Statistic/MeasureOfDispersion.php

@@ -68,7 +68,7 @@ final class MeasureOfDispersion
      *
      * @return float
      *
-     * @throws \Exception
+     * @throws ZeroDevisionException This exception is thrown if the mean is 0
      *
      * @since  1.0.0
      */
@@ -123,7 +123,7 @@ final class MeasureOfDispersion
      *
      * @return float
      *
-     * @throws \Exception
+     * @throws ZeroDevisionException This exception is thrown if the size of the values array is less than 2
      *
      * @since  1.0.0
      */
@@ -153,7 +153,7 @@ final class MeasureOfDispersion
      *
      * @return float
      *
-     * @throws \Exception
+     * @throws ZeroDevisionException This exception is thrown if the values array is empty
      *
      * @since  1.0.0
      */
@@ -190,7 +190,8 @@ final class MeasureOfDispersion
      *
      * @return float
      *
-     * @throws InvalidDimensionException
+     * @throws ZeroDevisionException This exception is thrown if the size of the x array is less than 2
+     * @throws InvalidDimensionException This exception is thrown if x and y have different dimensions
      *
      * @since  1.0.0
      */

Message/Console/Response.php

@@ -120,7 +120,7 @@ final class Response extends ResponseAbstract implements RenderableInterface
      *
      * @return string
      *
-     * @throws \Exception
+     * @throws \Exception This exception is thrown if the response cannot be rendered.
      *
      * @since  1.0.0
      */

Message/Http/Request.php

@@ -391,6 +391,8 @@ final class Request extends RequestAbstract
      *
      * @return bool
      *
+     * @throws \OutOfRangeException This exception is thrown if the port is out of range
+     *
      * @since  1.0.0
      */
     public function isHttps(int $port = 443) : bool

Module/ModuleManager.php

@@ -468,10 +468,12 @@ final class ModuleManager
             $this->installDependencies($info->getDependencies());
             $this->installModule($info);
 
-            /* Install providing */
+            /* Install providing but only if receiving module is already installed */
             $providing = $info->getProviding();
             foreach ($providing as $key => $version) {
-                $this->installProviding($module, $key);
+                if (isset($installed[$key])) {
+                    $this->installProviding($module, $key);
+                }
             }
 
             /* Install receiving */

Utils/Barcode/C25.php

@@ -84,6 +84,8 @@ class C25 extends C128Abstract
      *
      * @return void
      *
+     * @throws \InvalidArgumentException This exception is thrown if the content string is not supported.
+     *
      * @since  1.0.0
      */
     public function setContent(string $content) : void

Utils/Converter/Currency.php

@@ -71,6 +71,8 @@ class Currency
      *
      * @return float
      *
+     * @throws \InvalidArgumentException This exception is thrown if the currency to convert to doesn't exist
+     *
      * @since  1.0.0
      */
     public static function fromEurTo(float $value, string $to) : float
@@ -90,7 +92,7 @@ class Currency
      *
      * @return array<string, float>
      *
-     * @throws \Exception
+     * @throws \Exception This exception is thrown if the XML is malformed
      *
      * @since  1.0.0
      */
@@ -126,6 +128,8 @@ class Currency
      *
      * @return float
      *
+     * @throws \InvalidArgumentException This exception is thrown if the currency to convert from doesn't exist
+     *
      * @since  1.0.0
      */
     public static function fromToEur(float $value, string $from) : float
@@ -149,6 +153,8 @@ class Currency
      *
      * @return float
      *
+     * @throws \InvalidArgumentException This exception is thrown if either the from or to currency doesn't exist
+     *
      * @since  1.0.0
      */
     public static function convertCurrency(float $value, string $from, string $to) : float

Utils/Git/Git.php

@@ -76,7 +76,7 @@ class Git
      *
      * @return void
      *
-     * @throws PathException
+     * @throws PathException This exceptio is thrown if the binary path doesn't exist
      *
      * @since  1.0.0
      */

Utils/Parser/Php/ArrayParser.php

@@ -59,6 +59,8 @@ class ArrayParser
      *
      * @return string
      *
+     * @throws \UnexpectedValueException Throws this exception if the value cannot be parsed (invalid data type)
+     *
      * @since  1.0.0
      */
     public static function parseVariable($value, int $depth = 1) : string

Utils/Permutation.php

@@ -106,7 +106,8 @@ final class Permutation
      *
      * @return mixed
      *
-     * @throws \Exception
+     * @throws \InvalidArgumentException This exception is thrown if the $toPermute argument is neither array or string
+     * @throws \OutOfBoundsException This exception is thrown if the permutation key is larger than the data to permute
      *
      * @since  1.0.0
      */
@@ -119,7 +120,7 @@ final class Permutation
         $length = \is_array($toPermute) ? \count($toPermute) : \strlen($toPermute);
 
         if (\count($key) > $length) {
-            throw new \InvalidArgumentException('There mustn not be more keys than permutation elements.');
+            throw new \OutOfBoundsException('There mustn not be more keys than permutation elements.');
         }
 
         $i = 0;

Utils/TaskSchedule/TaskFactory.php

@@ -35,7 +35,7 @@ final class TaskFactory
      *
      * @return TaskAbstract
      *
-     * @throws \Exception
+     * @throws \Exception This exception is thrown if the operating system is not supported
      *
      * @since  1.0.0
      */

Validation/Validator.php

@@ -35,7 +35,7 @@ final class Validator extends ValidatorAbstract
      *
      * @return bool
      *
-     * @throws \Exception
+     * @throws \BadFunctionCallException This exception is thrown if the callback is not callable.
      *
      * @since  1.0.0
      */
@@ -49,7 +49,7 @@ final class Validator extends ValidatorAbstract
             $callback = StringUtils::endsWith($test, 'Not') ? \substr($test, 0, -3) : (string) $test;
 
             if (!\is_callable($callback)) {
-                throw new \Exception();
+                throw new \BadFunctionCallException();
             }
 
             $valid = !empty($settings) ? $callback($var, ...$settings) : $callback($var);

tests/Utils/PermutationTest.php

@@ -56,7 +56,7 @@ class PermutationTest extends \PHPUnit\Framework\TestCase
     }
 
     /**
-     * @expectedException \InvalidArgumentException
+     * @expectedException \OutOfBoundsException
      */
     public function testWrongPermuteKeyLength()
     {