Improve documentation

Author: Riimu

CHANGES.md

@@ -1,5 +1,9 @@
 # Changelog #
 
+## v2.3.0 (2017-07-15) ##
+
+  * 
+
 ## v2.2.0 (2017-07-08) ##
 
   * Increase the minimum PHP version requirement to 5.6

examples/export_difference.php

@@ -0,0 +1,35 @@
+<?php
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$precision = 17;
+$normalEncoder = new \Riimu\Kit\PHPEncoder\PHPEncoder(['float.precision' => $precision]);
+$exportEncoder = new \Riimu\Kit\PHPEncoder\PHPEncoder(['float.export' => true]);
+
+ini_set('serialize_precision', $precision);
+
+$count = 0;
+$mindiff = 1;
+$maxdiff = 0;
+$total = 0;
+
+for ($i = 0; $i <= 2 ** 53; $i++) {
+    $normal = $normalEncoder->encode($i / 2 ** 53); // $i / 2 ** 53
+    $export = $exportEncoder->encode($i / 2 ** 53); // $i / 2 ** 53
+
+    $normalResult = eval("return $normal;");
+    $exportResult = eval("return $export;");
+
+    if ($normalResult !== $exportResult) {
+        $diff = abs($normalResult - $exportResult);
+
+        $count++;
+        $mindiff = min($diff, $mindiff);
+        $maxdiff = max($diff, $maxdiff);
+        $total += $diff;
+        $avgdiff = $total / $count;
+        $pct = round($count / $i * 100, 2);
+
+        echo "Different ($count / $i, $pct%): $normal, $export, Diff: $mindiff / $avgdiff / $maxdiff\n";
+    }
+}

src/Encoder/IntegerEncoder.php

@@ -60,16 +60,32 @@ public function encode($value, $depth, array $options, callable $encode)
         return $callback((int) $value, $options);
     }
 
+    /**
+     * Encodes an integer into binary representation.
+     * @param int $integer The integer to encode
+     * @return string The PHP code representation for the integer
+     */
     public function encodeBinary($integer)
     {
         return sprintf('%s0b%s', $this->sign($integer), decbin(abs($integer)));
     }
 
+    /**
+     * Encodes an integer into octal representation.
+     * @param int $integer The integer to encode
+     * @return string The PHP code representation for the integer
+     */
     public function encodeOctal($integer)
     {
         return sprintf('%s0%s', $this->sign($integer), decoct(abs($integer)));
     }
 
+    /**
+     * Encodes an integer into decimal representation.
+     * @param int $integer The integer to encode
+     * @param array $options The integer encoding options
+     * @return string The PHP code representation for the integer
+     */
     public function encodeDecimal($integer, $options)
     {
         if ($integer === 1 << (PHP_INT_SIZE * 8 - 1)) {
@@ -79,11 +95,21 @@ public function encodeDecimal($integer, $options)
         return var_export($integer, true);
     }
 
+    /**
+     * Encodes an integer into hexadecimal representation.
+     * @param int $integer The integer to encode
+     * @return string The PHP code representation for the integer
+     */
     public function encodeHexadecimal($integer)
     {
         return sprintf('%s0x%s', $this->sign($integer), dechex(abs($integer)));
     }
 
+    /**
+     * Returns the negative sign for negative numbers.
+     * @param int $integer The number to test for negativity
+     * @return string The minus sign for negative numbers and empty string for positive numbers
+     */
     private function sign($integer)
     {
         if ($integer < 0) {

src/Encoder/ObjectEncoder.php

@@ -66,6 +66,7 @@ private function encodeObject($object, array $options, callable $encode)
      * @param array $options List of encoder options
      * @param callable $encode Callback used to encode values
      * @return string The object encoded as string
+     * @throws \RuntimeException If the object format is invalid
      */
     private function encodeObjectArray($object, array $options, callable $encode)
     {

src/Encoder/StringEncoder.php

@@ -42,6 +42,12 @@ public function encode($value, $depth, array $options, callable $encode)
         return $this->getSingleQuotedString($value);
     }
 
+    /**
+     * Tells if the string is not a valid UTF-8 string.
+     * @param string $string The string to test
+     * @param array $options The string encoding options
+     * @return bool True if the string is not valid UTF-8 and false if it is
+     */
     private function isBinaryString($string, $options)
     {
         if (!$options['string.binary']) {
@@ -64,6 +70,11 @@ private function isBinaryString($string, $options)
         return !preg_match($pattern, $string);
     }
 
+    /**
+     * Encodes the given string into base 64 encoded format.
+     * @param string $string The string to encode
+     * @return string A base 64 PHP code representation for the string
+     */
     private function encodeBinaryString($string)
     {
         return sprintf("base64_decode('%s')", base64_encode($string));
@@ -110,7 +121,7 @@ function ($matches) {
     }
 
     /**
-     * Encodes all multibyte UTF-8 characters into PHP7 string encoding
+     * Encodes all multibyte UTF-8 characters into PHP7 string encoding.
      * @param string $string The string to encoder
      * @return string The string with all the multibyte characters encoded
      */