Added docblocks to ByteFormatter and Base.

Moved testAutomaticUnitSwitching() from ByteFormatterTest to SymbolDecoratorTest.
Minor copy edit in README.

Author: Bilge

README.md

@@ -5,7 +5,7 @@ ByteFormatter
 [![Build status][Build image]][Build]
 
 ByteFormatter is a [PSR-2](http://www.php-fig.org/psr/psr-2/) compliant PHP library that formats byte values as
-human-readable strings. An appropriate scale is calculated automatically such that the value never exceeds the base.
+human-readable strings. An appropriate exponent is calculated automatically such that the value never exceeds the base.
 For example, in base 1024, `format(1023)` gives *1023 B* but `format(1024)` gives *1 KiB* instead of *1024 B*.
 
 Requirements
@@ -162,4 +162,3 @@ in this document can be found in `DocumentationTest`.
   [Version image]: http://img.shields.io/github/tag/ScriptFUSION/ByteFormatter.svg "Latest version"
   [Build]: http://travis-ci.org/ScriptFUSION/ByteFormatter
   [Build image]: http://img.shields.io/travis/ScriptFUSION/ByteFormatter.svg "Build status"
-

src/Byte/Base.php

@@ -1,6 +1,9 @@
 <?php
 namespace ScriptFUSION\Byte;
 
+/**
+ * Specifies an exponentiation base.
+ */
 final class Base
 {
     const

src/Byte/ByteFormatter.php

@@ -17,15 +17,21 @@ class ByteFormatter
     /** @var string */
     private $format;
 
+    /** @var string */
+    private $sprintfFormat;
+
     /** @var int */
     private $precision = 0;
 
-    /** @var string */
-    private $normalizedFormat;
-
     /** @var UnitDecorator */
     private $unitDecorator;
 
+    /**
+     * Initializes this instance, optionally with a specific unit decorator.
+     * If no unit decorator is specified, SymbolDecorator will be used.
+     *
+     * @param UnitDecorator|null $unitDecorator Optional. Unit decorator.
+     */
     public function __construct(UnitDecorator $unitDecorator = null)
     {
         $this
@@ -34,51 +40,105 @@ public function __construct(UnitDecorator $unitDecorator = null)
         ;
     }
 
+    /**
+     * Formats the specified number of bytes as a human-readable string.
+     *
+     * @param int $bytes Number of bytes.
+     * @param int|null $precision Optional. Number of fractional digits.
+     *
+     * @return string Formatted bytes.
+     */
     public function format($bytes, $precision = null)
     {
-        $precision = $precision === null ? $this->precision : $precision;
+        // Use default precision when not specified.
+        $precision === null && $precision = $this->precision;
+
         $log = log($bytes, $this->base);
         $exponent = max(0, $log|0);
         $value = round(pow($this->base, $log - $exponent), $precision);
         $units = $this->getUnitDecorator()->decorate($exponent, $this->base, $value);
 
-        return trim(sprintf($this->normalizedFormat, $value, $units));
+        return trim(sprintf($this->sprintfFormat, $value, $units));
     }
 
-    private function normalizeFormat($format)
+    /**
+     * Coverts a format specifier into a sprintf() compatible format.
+     *
+     * @param string $format Format specifier.
+     *
+     * @return string sprintf() format.
+     */
+    private function convertFormat($format)
     {
         return str_replace(['%v', '%u'], ['%1$s', '%2$s'], $format);
     }
 
+    /**
+     * Gets the exponentiation base.
+     *
+     * @return int Exponentiation base.
+     */
     public function getBase()
     {
         return $this->base;
     }
 
+    /**
+     * Sets the exponentiation base which should usually be a Base constant.
+     *
+     * @param int $base Exponentiation base.
+     *
+     * @return $this
+     */
     public function setBase($base)
     {
         $this->base = $base|0;
 
         return $this;
     }
 
+    /**
+     * Gets the format specifier.
+     *
+     * @return string Format specifier.
+     */
     public function getFormat()
     {
         return $this->format;
     }
 
+    /**
+     * Sets the format specifier. Occurrences of %v and %u will be replaced
+     * with formatted byte values and units, respectively.
+     *
+     * @param string $format Format specifier.
+     *
+     * @return $this
+     */
     public function setFormat($format)
     {
-        $this->normalizedFormat = $this->normalizeFormat($this->format = "$format");
+        $this->sprintfFormat = $this->convertFormat($this->format = "$format");
 
         return $this;
     }
 
+    /**
+     * Gets the maximum number of fractional digits.
+     *
+     * @return int Fractional digits.
+     */
     public function getPrecision()
     {
         return $this->precision;
     }
 
+    /**
+     * Sets the maximum number of fractional digits.
+     *
+     * @param $precision
+     *
+     * @return $this
+     */
     public function setPrecision($precision)
     {
         $this->precision = $precision|0;
@@ -87,16 +147,25 @@ public function setPrecision($precision)
     }
 
     /**
+     * Gets the unit decorator.
+     *
      * @return UnitDecorator
      */
     public function getUnitDecorator()
     {
         return $this->unitDecorator;
     }
 
-    public function setUnitDecorator(UnitDecorator $collection)
+    /**
+     * Sets the unit decorator.
+     *
+     * @param UnitDecorator $decorator Unit decorator.
+     *
+     * @return $this
+     */
+    public function setUnitDecorator(UnitDecorator $decorator)
     {
-        $this->unitDecorator = $collection;
+        $this->unitDecorator = $decorator;
 
         return $this;
     }

test/Integration/Byte/ByteFormatterTest.php

@@ -119,17 +119,6 @@ public function provideFormats()
         ];
     }
 
-    public function testAutomaticUnitSwitching()
-    {
-        $formatter = $this->formatter->setUnitDecorator(new SymbolDecorator);
-
-        $formatter->setBase(Base::BINARY);
-        $this->assertSame('1KiB', $formatter->format($formatter->getBase()));
-
-        $formatter->setBase(Base::DECIMAL);
-        $this->assertSame('1KB', $formatter->format($formatter->getBase()));
-    }
-
     public function testCustomUnitSequence()
     {
         $formatter = (new ByteFormatter)->setUnitDecorator(

test/Unit/Byte/Unit/SymbolDecoratorTest.php

@@ -1,6 +1,7 @@
 <?php
 namespace ScriptFUSIONTest\Unit\Byte\Unit;
 
+use ScriptFUSION\Byte\Base;
 use ScriptFUSION\Byte\Unit\SymbolDecorator;
 
 final class SymbolDecoratorTest extends \PHPUnit_Framework_TestCase
@@ -40,4 +41,12 @@ public function testIecSuffix()
             $this->assertSame($symbol, $decorator->decorate($exponent, 0, 0));
         }
     }
+
+    public function testAutomaticUnitSwitching()
+    {
+        $decorator = new SymbolDecorator;
+
+        $this->assertSame('KiB', $decorator->decorate(1, Base::BINARY, 0));
+        $this->assertSame('KB', $decorator->decorate(1, Base::DECIMAL, 0));
+    }
 }