Merge pull request #71 from Orange-Management/documentation

Documentation

Autoloader.php

@@ -39,7 +39,7 @@ class Autoloader
      *
      * @return void
      *
-     * @throws
+     * @throws \Exception Throws this exception if the class to autoload doesn't exist. This could also be related to a wrong namespace/file path correlation.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn <d.eichhorn@oms.com>

DataStorage/Database/DataMapperAbstract.php

@@ -263,6 +263,16 @@ class DataMapperAbstract implements DataMapperInterface
         return __CLASS__;
     }
 
+    /**
+     * Resets all loaded mapper variables.
+     *
+     * This is used after one action is performed otherwise other models would use wrong settings.
+     *
+     * @return void
+     *
+     * @since  1.0.0
+     * @author Dennis Eichhorn <d.eichhorn@oms.com>
+     */
     public static function clear()
     {
         self::$overwrite    = true;

DataStorage/Database/Query/Grammar/Grammar.php

@@ -237,9 +237,9 @@ class Grammar extends GrammarAbstract
      * @param array|string|\Closure $value  Value
      * @param string                $prefix Prefix in case value is a table
      *
-     * @return string
+     * @return string Returns a string representation of the value.
      *
-     * @throws \InvalidArgumentException
+     * @throws \InvalidArgumentException Throws this exception if the value to compile is not supported by this function.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn <d.eichhorn@oms.com>

Datatypes/Enum.php

@@ -88,7 +88,7 @@ abstract class Enum
      *
      * @return mixed
      *
-     * @throws \Exception
+     * @throws \Exception Throws this exception if the constant is not defined in the enum class.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn <d.eichhorn@oms.com>

Math/Statistic/Forecast/Error.php

@@ -142,7 +142,9 @@ class Error
     /**
      * Goodness of fit.
      *
-     * Evaluating how well the observed data fit the linear regression model
+     * Evaluating how well the observed data fit the linear regression model.
+     *
+     * @latex R^{2} = \frac{\sum \left(\hat{y}_{i} - \bar{y}\right)^2}{\sum \left(y_{i} - \bar{y}\right)^2}
      *
      * @param array $observed   Obersved y values
      * @param array $forecasted Forecasted y values

Math/Statistic/Forecast/Regression/LevelLogRegression.php

@@ -30,17 +30,7 @@ namespace phpOMS\Math\Statistic\Forecast\Regression;
 class LevelLogRegression extends RegressionAbstract
 {
     /**
-     * Get linear regression based on scatter plot.
-     *
-     * y = b0 + b1 * x
-     *
-     * @param array $x Obersved x values
-     * @param array $y Observed y values
-     *
-     * @return array [b0 => ?, b1 => ?]
-     *
-     * @since  1.0.0
-     * @author Dennis Eichhorn <d.eichhorn@oms.com>
+     * {@inheritdoc}
      */
     public static function getRegression(array $x, array $y) : array
     {

Math/Statistic/Forecast/Regression/LogLevelRegression.php

@@ -30,17 +30,7 @@ namespace phpOMS\Math\Statistic\Forecast\Regression;
 class LogLevelRegression extends RegressionAbstract
 {
     /**
-     * Get linear regression based on scatter plot.
-     *
-     * y = b0 + b1 * x
-     *
-     * @param array $x Obersved x values
-     * @param array $y Observed y values
-     *
-     * @return array [b0 => ?, b1 => ?]
-     *
-     * @since  1.0.0
-     * @author Dennis Eichhorn <d.eichhorn@oms.com>
+     * {@inheritdoc}
      */
     public static function getRegression(array $x, array $y) : array
     {

Math/Statistic/Forecast/Regression/LogLogRegression.php

@@ -30,17 +30,7 @@ namespace phpOMS\Math\Statistic\Forecast\Regression;
 class LogLogRegression extends RegressionAbstract
 {
     /**
-     * Get linear regression based on scatter plot.
-     *
-     * y = b0 + b1 * x
-     *
-     * @param array $x Obersved x values
-     * @param array $y Observed y values
-     *
-     * @return array [b0 => ?, b1 => ?]
-     *
-     * @since  1.0.0
-     * @author Dennis Eichhorn <d.eichhorn@oms.com>
+     * {@inheritdoc}
      */
     public static function getRegression(array $x, array $y) : array
     {

Math/Statistic/Forecast/Regression/MultipleLinearRegression.php

@@ -4,6 +4,9 @@ namespace phpOMS\Math\Statistic\Forecast\Regression;
 
 class MultipleLinearRegression
 {
+    /**
+     * {@inheritdoc}
+     */
     public static function getRegression(array $x, array $y) : array
     {
         $X = new Matrix(count($x), count($x[0]));

Math/Statistic/Forecast/Regression/RegressionAbstract.php

@@ -11,7 +11,7 @@ abstract class RegressionAbstract
     /**
      * Get linear regression based on scatter plot.
      *
-     * y = b0 + b1 * x
+     * @latex y = b_{0} + b_{1} \cdot x
      *
      * @param array $x Obersved x values
      * @param array $y Observed y values
@@ -37,6 +37,8 @@ abstract class RegressionAbstract
      *
      * Used in order to evaluate the performance of the linear regression
      *
+     * @latex s_{e} = \sqrt{\frac{1}{N - 2}\sum_{i = 1}^{N} e_{i}^{2}}
+     *
      * @param array $errors Errors (e = y - y_forecasted)
      *
      * @return float
@@ -88,6 +90,8 @@ abstract class RegressionAbstract
     /**
      * Get linear regression parameter beta 1.
      *
+     * @latex \beta_{1} = \frac{\sum_{i=1}^{N} \left(y_{i} - \bar{y}\right)\left(x_{i} - \bar{x}\right)}{\sum_{i=1}^{N} \left(x_{i} - \bar{x}\right)^{2}}
+     *
      * @param array $x Obersved x values
      * @param array $y Observed y values
      *
@@ -116,6 +120,8 @@ abstract class RegressionAbstract
     /**
      * Get linear regression parameter beta 0.
      *
+     * @latex \beta_{0} = \bar{x} - b_{1} \cdot \bar{x}
+     *
      * @param array $x  Obersved x values
      * @param array $y  Observed y values
      * @param float $b1 Beta 1

Utils/StringUtils.php

@@ -16,7 +16,9 @@
 namespace phpOMS\Utils;
 
 /**
- * String utils.
+ * String utils class.
+ *
+ * This class provides static helper functionalities for strings.
  *
  * @category   Framework
  * @package    phpOMS\Utils
@@ -32,6 +34,8 @@ class StringUtils
     /**
      * Constructor.
      *
+     * This class is purely static and is preventing any initialization
+     *
      * @since  1.0.0
      * @author Dennis Eichhorn <d.eichhorn@oms.com>
      */
@@ -40,12 +44,18 @@ class StringUtils
     }
 
     /**
-     * Contains any string
+     * Check if a string contains any of the provided needles.
+     *
+     * The validation is done case sensitive.
      *
      * @param string $haystack Haystack
-     * @param array  $needles  Needles
+     * @param array  $needles  Needles to check if any of them are part of the haystack
      *
-     * @return bool
+     * @example StringUtils::contains('This string', ['This', 'test']); // true
+     * @example StringUtils::contains('This string', 'is st'); // true
+     * @example StringUtils::contains('This string', 'something'); // false
+     *
+     * @return bool The function returns true if any of the needles is part of the haystack, false otherwise.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -62,12 +72,19 @@ class StringUtils
     }
 
     /**
-     * String ends with?
+     * Tests if a string ends with a certain string.
+     *
+     * The validation is done case sensitive. The function takes strings or an array of strings for the validation.
+     * In case of an array the function will test if any of the needles is at the end of the haystack string.
      *
      * @param string       $haystack Haystack
-     * @param string|array $needles  Needles
+     * @param string|array $needles  Needles to check if they are at the end of the haystack.
      *
-     * @return bool
+     * @example StringUtils::endsWith('Test string', ['test1', 'string']); // true
+     * @example StringUtils::endsWith('Test string', 'string'); // true
+     * @example StringUtils::endsWith('Test string', 'String'); // false
+     *
+     * @return bool The function returns true if any of the needles is at the end of the haystack, false otherwise.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -88,12 +105,19 @@ class StringUtils
     }
 
     /**
-     * String starts with?
+     * Tests if a string starts with a certain string.
+     *
+     * The validation is done case sensitive. The function takes strings or an array of strings for the validation.
+     * In case of an array the function will test if any of the needles is at the beginning of the haystack string.
      *
      * @param string       $haystack Haystack
-     * @param string|array $needles  Needles
+     * @param string|array $needles  Needles to check if they are at the beginning of the haystack.
      *
-     * @return bool
+     * @example StringUtils::startsWith('Test string', ['Test', 'something']); // true
+     * @example StringUtils::startsWith('Test string', 'string'); // false
+     * @example StringUtils::startsWith('Test string', 'Test'); // true
+     *
+     * @return bool The function returns true if any of the needles is at the beginning of the haystack, false otherwise.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -114,12 +138,15 @@ class StringUtils
     }
 
     /**
-     * String starts with?
+     * Tests if a multi byte string starts with a certain string.
+     *
+     * The validation is done case sensitive. The function takes strings or an array of strings for the validation.
+     * In case of an array the function will test if any of the needles is at the beginning of the haystack string.
      *
      * @param string       $haystack Haystack
-     * @param string|array $needles  Needles
+     * @param string|array $needles  Needles to check if they are at the beginning of the haystack.
      *
-     * @return bool
+     * @return bool The function returns true if any of the needles is at the beginning of the haystack, false otherwise.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -140,12 +167,19 @@ class StringUtils
     }
 
     /**
-     * String ends with?
+     * Tests if a multi byte string ends with a certain string.
+     *
+     * The validation is done case sensitive. The function takes strings or an array of strings for the validation.
+     * In case of an array the function will test if any of the needles is at the end of the haystack string.
      *
      * @param string       $haystack Haystack
-     * @param string|array $needles  Needles
+     * @param string|array $needles  Needles to check if they are at the end of the haystack.
      *
-     * @return bool
+     * @example StringUtils::endsWith('Test string', ['test1', 'string']); // true
+     * @example StringUtils::endsWith('Test string', 'string'); // true
+     * @example StringUtils::endsWith('Test string', String); // false
+     *
+     * @return bool The function returns true if any of the needles is at the end of the haystack, false otherwise.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -166,11 +200,11 @@ class StringUtils
     }
 
     /**
-     * Uppercase first letter.
+     * Makes first letter of a multi byte string upper case.
      *
-     * @param string $string String to manipulate
+     * @param string $string String to upper case first letter.
      *
-     * @return string
+     * @return string Multi byte string with first character as upper case.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -185,11 +219,11 @@ class StringUtils
     }
 
     /**
-     * Lowercase first letter.
+     * Makes first letter of a multi byte string lower case.
      *
-     * @param string $string String to manipulate
+     * @param string $string String to lower case first letter.
      *
-     * @return string
+     * @return string Multi byte string with first character as lower case.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -204,12 +238,12 @@ class StringUtils
     }
 
     /**
-     * Trim string.
+     * Trim multi byte characters from a multi byte string.
      *
-     * @param string $string   String to manipulate
-     * @param string $charlist String to trim
+     * @param string $string   Multi byte string to trim multi byte characters from.
+     * @param string $charlist Multi byte character list used for trimming
      *
-     * @return string
+     * @return string Trimmed multi byte string.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -226,12 +260,12 @@ class StringUtils
     }
 
     /**
-     * Trim right part of string.
+     * Trim multi byte characters from the right of a multi byte string.
      *
-     * @param string $string   String to manipulate
-     * @param string $charlist String to trim
+     * @param string $string   Multi byte string to trim multi byte characters from.
+     * @param string $charlist Multi byte character list used for trimming
      *
-     * @return string
+     * @return string Trimmed multi byte string.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -248,12 +282,12 @@ class StringUtils
     }
 
     /**
-     * Trim left part of string.
+     * Trim multi byte characters from the left of a multi byte string.
      *
-     * @param string $string   String to manipulate
-     * @param string $charlist String to trim
+     * @param string $string   Multi byte string to trim multi byte characters from.
+     * @param string $charlist Multi byte character list used for trimming
      *
-     * @return string
+     * @return string Trimmed multi byte string.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn
@@ -270,12 +304,15 @@ class StringUtils
     }
 
     /**
-     * Count occurences of character at the beginning of string.
+     * Count occurences of character at the beginning of a string.
      *
-     * @param string $string    String to manipulate
-     * @param string $character Character to count
+     * @param string $string    String to analyze.
+     * @param string $character Character to count at the beginning of the string.
      *
-     * @return int
+     * @example StringUtils::countCharacterFromStart('    Test string', ' '); // 4
+     * @example StringUtils::countCharacterFromStart('    Test string', 's'); // 0
+     *
+     * @return int The amount of repeating occurences at the beginning of the string.
      *
      * @since  1.0.0
      * @author Dennis Eichhorn

Validation/Base/CreditCard.php

@@ -72,7 +72,17 @@ abstract class CreditCard extends ValidatorAbstract
         return ($total % 10 == 0) ? true : false;
     }
 
-    public static function luhnTest(string $num)
+    /**
+     * Luhn algorithm or mod 10 algorithm is used to verify credit cards.
+     *
+     * @param string $num Credit card number.
+     *
+     * @return bool Returns true if the number is a valid credit card and false if it isn't.
+     *
+     * @since  1.0.0
+     * @author Dennis Eichhorn <d.eichhorn@oms.com>
+     */
+    public static function luhnTest(string $num) : bool
     {
         $len = strlen($num);
         $sum = 0;