Update documentation for v0.8.0

docs/files/Calculator/AbstractCalculator.php.txt

@@ -1,4 +1,6 @@
-<?php declare(strict_types = 1);
+<?php
+
+declare(strict_types = 1);
 
 /**
  * This file is part of the jordanbrauer/unit-converter PHP package.
@@ -24,42 +26,58 @@ namespace UnitConverter\Calculator;
 abstract class AbstractCalculator implements CalculatorInterface
 {
     /**
-     * @const int DEFAULT_PRECISION The default precision value.
+     * The default precision value.
+     *
+     * @const int DEFAULT_PRECISION
      */
     const DEFAULT_PRECISION = 2;
 
     /**
-     * @const int DEFAULT_ROUNDING_MODE The default rounding mode for calculators.
+     * The default rounding mode for calculators.
+     *
+     * @const int DEFAULT_ROUNDING_MODE
      */
     const DEFAULT_ROUNDING_MODE = self::ROUND_HALF_UP;
 
     /**
-     * @const int ROUND_HALF_UP Makes 1.5 into 2 and -1.5 into -2.
-     */
-    const ROUND_HALF_UP = PHP_ROUND_HALF_UP;
-
-    /**
-     * @const int ROUND_HALF_DOWN Makes 1.5 into 1 and -1.5 into -1.
+     * Makes 1.5 into 1 and -1.5 into -1.
+     *
+     * @const int ROUND_HALF_DOWN
      */
     const ROUND_HALF_DOWN = PHP_ROUND_HALF_DOWN;
 
     /**
-     * @const int ROUND_HALF_EVEN Rounds to the nearest even value.
+     * Rounds to the nearest even value.
+     *
+     * @const int ROUND_HALF_EVEN
      */
     const ROUND_HALF_EVEN = PHP_ROUND_HALF_EVEN;
 
     /**
-     * @const int ROUND_HALF_ODD Rounds to the nearest odd value.
+     * Rounds to the nearest odd value.
+     *
+     * @const int ROUND_HALF_ODD
      */
     const ROUND_HALF_ODD = PHP_ROUND_HALF_ODD;
 
     /**
-     * @var int $precision The number of decimal places that will calculated
+     * Makes 1.5 into 2 and -1.5 into -2.
+     *
+     * @const int ROUND_HALF_UP
+     */
+    const ROUND_HALF_UP = PHP_ROUND_HALF_UP;
+
+    /**
+     * The number of decimal places that will calculated
+     *
+     * @var int $precision
      */
     protected $precision;
 
     /**
-     * @var int $roundingMode The mode in which rounding occurs. Use one of the PHP_ROUND_HALF_* constants.
+     * The mode in which rounding occurs. Use one of the PHP_ROUND_HALF_* constants.
+     *
+     * @var int $roundingMode
      */
     protected $roundingMode;
 
@@ -71,48 +89,103 @@ abstract class AbstractCalculator implements CalculatorInterface
      *
      * @param int $precision The number of decimal digits to round to.
      * @param int $roundingMode The mode in which rounding occurs.
+     * @return self
      */
-    public function __construct (int $precision = null, int $roundingMode = null)
+    public function __construct(int $precision = null, int $roundingMode = null)
     {
         $this->setPrecision(($precision ?? self::DEFAULT_PRECISION));
         $this->setRoundingMode(($roundingMode ?? self::DEFAULT_ROUNDING_MODE));
     }
 
-    public function setPrecision (int $precision): CalculatorInterface
-    {
-        $this->precision = $precision;
-        return $this;
-    }
+    /**
+     * {@inheritDoc}
+     */
+    abstract public function add($leftOperand, $rightOperand);
+
+    /**
+     * {@inheritDoc}
+     */
+    abstract public function div($dividend, $divisor);
 
-    public function setRoundingMode (int $roundingMode): CalculatorInterface
+    /**
+     * Syntacital sugar wrapper method for div.
+     *
+     * @api
+     * @uses CalculatorInterface::div
+     */
+    public function divide(...$params)
     {
-        $this->roundingMode = $roundingMode;
-        return $this;
+        return $this->div(...$params);
     }
 
-    public function getPrecision (): ?int
+    /**
+     * {@inheritDoc}
+     */
+    public function getPrecision(): ?int
     {
         return $this->precision;
     }
 
-    public function getRoundingMode (): ?int
+    /**
+     * {@inheritDoc}
+     */
+    public function getRoundingMode(): ?int
     {
         return $this->roundingMode;
     }
 
-    abstract public function add ($leftOperand, $rightOperand);
+    /**
+     * {@inheritDoc}
+     */
+    abstract public function mod($dividend, $modulus);
 
-    abstract public function sub ($leftOperand, $rightOperand);
+    /**
+     * Syntacital sugar wrapper method for mod
+     *
+     * @api
+     * @uses CalculatorInterface::mod
+     */
+    public function modulus(...$params)
+    {
+        return $this->mod(...$params);
+    }
 
-    abstract public function mul ($leftOperand, $rightOperand);
+    /**
+     * {@inheritDoc}
+     */
+    abstract public function mul($leftOperand, $rightOperand);
 
-    abstract public function div ($dividend, $divisor);
+    /**
+     * Syntacital sugar wrapper method for mul
+     *
+     * @api
+     * @uses CalculatorInterface::mul
+     */
+    public function multiply(...$params)
+    {
+        return $this->mul(...$params);
+    }
 
-    abstract public function mod ($dividend, $modulus);
+    /**
+     * {@inheritDoc}
+     */
+    abstract public function pow($base, $exponent);
 
-    abstract public function pow ($base, $exponent);
+    /**
+     * Syntacital sugar wrapper method for pow
+     *
+     * @api
+     * @uses CalculatorInterface::pow
+     */
+    public function power(...$params)
+    {
+        return $this->pow(...$params);
+    }
 
-    public function round ($value, int $precision = null): float
+    /**
+     * {@inheritDoc}
+     */
+    public function round($value, int $precision = null)
     {
         return round(
             $value,
@@ -122,43 +195,39 @@ abstract class AbstractCalculator implements CalculatorInterface
     }
 
     /**
-     * Syntacital sugar wrapper method for sub
+     * {@inheritDoc}
      */
-    public function subtract (...$params)
+    public function setPrecision(int $precision): CalculatorInterface
     {
-        return $this->sub(...$params);
-    }
+        $this->precision = $precision;
 
-    /**
-     * Syntacital sugar wrapper method for mul
-     */
-    public function multiply (...$params)
-    {
-        return $this->mul(...$params);
+        return $this;
     }
 
     /**
-     * Syntacital sugar wrapper method for div
+     * {@inheritDoc}
      */
-    public function divide (...$params)
+    public function setRoundingMode(int $roundingMode): CalculatorInterface
     {
-        return $this->div(...$params);
+        $this->roundingMode = $roundingMode;
+
+        return $this;
     }
 
     /**
-     * Syntacital sugar wrapper method for mod
+     * {@inheritDoc}
      */
-    public function modulus (...$params)
-    {
-        return $this->mod(...$params);
-    }
+    abstract public function sub($leftOperand, $rightOperand);
 
     /**
-     * Syntacital sugar wrapper method for pow
+     * Syntacital sugar wrapper method for sub
+     *
+     * @api
+     * @uses CalculatorInterface::sub
      */
-    public function power (...$params)
+    public function subtract(...$params)
     {
-        return $this->pow(...$params);
+        return $this->sub(...$params);
     }
 }
 

docs/files/Calculator/BinaryCalculator.php.txt

@@ -1,4 +1,6 @@
-<?php declare(strict_types = 1);
+<?php
+
+declare(strict_types = 1);
 
 /**
  * This file is part of the jordanbrauer/unit-converter PHP package.
@@ -16,61 +18,87 @@ namespace UnitConverter\Calculator;
  * A concrete calculator calss that uses the bcmath library
  * to perform mathematical operations.
  *
- * @HACK https://github.com/jordanbrauer/unit-converter/issues/54
- *
  * @link http://php.net/manual/en/book.bc.php
+ * @HACK https://github.com/jordanbrauer/unit-converter/issues/54
  *
  * @version 1.0.0
  * @since 0.4.1
  * @author Jordan Brauer <jbrauer.inc@gmail.com>
  */
 class BinaryCalculator extends AbstractCalculator
 {
-    public function setPrecision(int $precision): CalculatorInterface
+    /**
+     * {@inheritDoc}
+     */
+    public function add($leftOperand, $rightOperand)
     {
-        $precision = ($precision * 2); // HACK: #54
-        parent::setPrecision($precision);
-        bcscale($precision);
-        return $this;
+        return bcadd($leftOperand, $rightOperand);
     }
 
     /**
-     * Overwrites the default implementation for rounding. Simply
-     * casts the result to a string.
+     * {@inheritDoc}
      */
-    public function round ($value, int $precision = null): string
+    public function div($dividend, $divisor)
     {
-        return (string) parent::round($value, $precision);
+        return bcdiv($dividend, $divisor);
     }
 
-    public function add ($leftOperand, $rightOperand)
+    /**
+     * {@inheritDoc}
+     */
+    public function mod($dividend, $modulus)
     {
-        return bcadd($leftOperand, $rightOperand);
+        return bcmod($dividend, $modulus);
     }
 
-    public function sub ($leftOperand, $rightOperand)
+    /**
+     * {@inheritDoc}
+     */
+    public function mul($leftOperand, $rightOperand)
     {
-        return bcsub($leftOperand, $rightOperand);
+        return bcmul($leftOperand, $rightOperand);
     }
 
-    public function mul ($leftOperand, $rightOperand)
+    /**
+     * {@inheritDoc}
+     */
+    public function pow($base, $exponent)
     {
-        return bcmul($leftOperand, $rightOperand);
+        return bcpow($base, $exponent);
     }
 
-    public function div ($dividend, $divisor)
+    /**
+     * Overwrites the default implementation for rounding. Simply
+     * casts the result to a string.
+     *
+     * {@inheritDoc}
+     */
+    public function round($value, int $precision = null)
     {
-        return bcdiv($dividend, $divisor);
+        return (string) parent::round($value, $precision);
     }
 
-    public function mod ($dividend, $modulus)
+    /**
+     * Overwrites the default implementation for setting the precision to round
+     * values to.
+     *
+     * {@inheritDoc}
+     */
+    public function setPrecision(int $precision): CalculatorInterface
     {
-        return bcmod($dividend, $modulus);
+        $precision = ($precision * 2); // HACK: #54
+        parent::setPrecision($precision);
+        bcscale($precision);
+
+        return $this;
     }
 
-    public function pow ($base, $exponent)
+    /**
+     * {@inheritDoc}
+     */
+    public function sub($leftOperand, $rightOperand)
     {
-        return bcpow($base, $exponent);
+        return bcsub($leftOperand, $rightOperand);
     }
 }