Add docblocks for classes and interfaces in Ramsey\Uuid\Converter namespace

src/Converter/Number/BigNumberConverter.php

@@ -14,26 +14,41 @@
 
 namespace Ramsey\Uuid\Converter\Number;
 
+use Moontoast\Math\BigNumber;
 use Ramsey\Uuid\Converter\NumberConverterInterface;
 
+/**
+ * BigNumberConverter converts UUIDs from hexadecimal characters into
+ * moontoast/math `BigNumber` representations of integers and vice versa
+ */
 class BigNumberConverter implements NumberConverterInterface
 {
     /**
-     * @param string $hex
+     * Converts a hexadecimal number into a `Moontoast\Math\BigNumber` representation
+     *
+     * @param string $hex The hexadecimal string representation to convert
+     * @return BigNumber
      */
     public function fromHex($hex)
     {
-        $number = \Moontoast\Math\BigNumber::convertToBase10($hex, 16);
+        $number = BigNumber::convertToBase10($hex, 16);
 
-        return new \Moontoast\Math\BigNumber($number);
+        return new BigNumber($number);
     }
 
+    /**
+     * Converts an integer or `Moontoast\Math\BigNumber` integer representation
+     * into a hexadecimal string representation
+     *
+     * @param int|string|BigNumber $integer An integer or `Moontoast\Math\BigNumber`
+     * @return string Hexadecimal string
+     */
     public function toHex($integer)
     {
-        if (!$integer instanceof \Moontoast\Math\BigNumber) {
-            $integer = new \Moontoast\Math\BigNumber($integer);
+        if (!$integer instanceof BigNumber) {
+            $integer = new BigNumber($integer);
         }
 
-        return \Moontoast\Math\BigNumber::convertFromBase10($integer, 16);
+        return BigNumber::convertFromBase10($integer, 16);
     }
 }

src/Converter/Number/DegradedNumberConverter.php

@@ -17,8 +17,20 @@ namespace Ramsey\Uuid\Converter\Number;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 use Ramsey\Uuid\Converter\NumberConverterInterface;
 
+/**
+ * DegradedNumberConverter throws `UnsatisfiedDependencyException` exceptions
+ * if attempting to use number conversion functionality in an environment that
+ * does not support large integers (i.e. when moontoast/math is not available)
+ */
 class DegradedNumberConverter implements NumberConverterInterface
 {
+    /**
+     * Throws an `UnsatisfiedDependencyException`
+     *
+     * @param string $hex The hexadecimal string representation to convert
+     * @return void
+     * @throws UnsatisfiedDependencyException
+     */
     public function fromHex($hex)
     {
         throw new UnsatisfiedDependencyException(
@@ -28,6 +40,13 @@ class DegradedNumberConverter implements NumberConverterInterface
         );
     }
 
+    /**
+     * Throws an `UnsatisfiedDependencyException`
+     *
+     * @param mixed $integer An integer representation to convert
+     * @return void
+     * @throws UnsatisfiedDependencyException
+     */
     public function toHex($integer)
     {
         throw new UnsatisfiedDependencyException(

src/Converter/NumberConverterInterface.php

@@ -14,9 +14,31 @@
 
 namespace Ramsey\Uuid\Converter;
 
+/**
+ * NumberConverterInterface converts UUIDs from hexadecimal characters into
+ * representations of integers and vice versa
+ */
 interface NumberConverterInterface
 {
+    /**
+     * Converts a hexadecimal number into an integer representation of the number
+     *
+     * The integer representation returned may be an object or a string
+     * representation of the integer, depending on the implementation.
+     *
+     * @param string $hex The hexadecimal string representation to convert
+     * @return mixed
+     */
     public function fromHex($hex);
 
+    /**
+     * Converts an integer representation into a hexadecimal string representation
+     * of the number
+     *
+     * @param mixed $integer An integer representation to convert; this may be
+     *     a true integer, a string integer, or a object representation that
+     *     this converter can understand
+     * @return string Hexadecimal string
+     */
     public function toHex($integer);
 }

src/Converter/Time/BigNumberTimeConverter.php

@@ -14,18 +14,33 @@
 
 namespace Ramsey\Uuid\Converter\Time;
 
+use Moontoast\Math\BigNumber;
 use Ramsey\Uuid\Converter\TimeConverterInterface;
 
+/**
+ * BigNumberTimeConverter uses the moontoast/math library's `BigNumber` to
+ * provide facilities for converting parts of time into representations that may
+ * be used in UUIDs
+ */
 class BigNumberTimeConverter implements TimeConverterInterface
 {
+    /**
+     * Uses the provided seconds and micro-seconds to calculate the time_low,
+     * time_mid, and time_high fields used by RFC 4122 version 1 UUIDs
+     *
+     * @param string $seconds
+     * @param string $microSeconds
+     * @return string[] An array containing `low`, `mid`, and `high` keys
+     * @link http://tools.ietf.org/html/rfc4122#section-4.2.2
+     */
     public function calculateTime($seconds, $microSeconds)
     {
-        $uuidTime = new \Moontoast\Math\BigNumber('0');
+        $uuidTime = new BigNumber('0');
 
-        $sec = new \Moontoast\Math\BigNumber($seconds);
+        $sec = new BigNumber($seconds);
         $sec->multiply('10000000');
 
-        $usec = new \Moontoast\Math\BigNumber($microSeconds);
+        $usec = new BigNumber($microSeconds);
         $usec->multiply('10');
 
         $uuidTime->add($sec)

src/Converter/Time/DegradedTimeConverter.php

@@ -17,8 +17,21 @@ namespace Ramsey\Uuid\Converter\Time;
 use Ramsey\Uuid\Converter\TimeConverterInterface;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 
+/**
+ * DegradedTimeConverter throws `UnsatisfiedDependencyException` exceptions
+ * if attempting to use time conversion functionality in an environment that
+ * does not support large integers (i.e. when moontoast/math is not available)
+ */
 class DegradedTimeConverter implements TimeConverterInterface
 {
+    /**
+     * Throws an `UnsatisfiedDependencyException`
+     *
+     * @param string $seconds
+     * @param string $microSeconds
+     * @return void
+     * @throws UnsatisfiedDependencyException
+     */
     public function calculateTime($seconds, $microSeconds)
     {
         throw new UnsatisfiedDependencyException(

src/Converter/Time/PhpTimeConverter.php

@@ -16,8 +16,22 @@ namespace Ramsey\Uuid\Converter\Time;
 
 use Ramsey\Uuid\Converter\TimeConverterInterface;
 
+/**
+ * PhpTimeConverter uses built-in PHP functions and standard math operations
+ * available to the PHP programming language to provide facilities for
+ * converting parts of time into representations that may be used in UUIDs
+ */
 class PhpTimeConverter implements TimeConverterInterface
 {
+    /**
+     * Uses the provided seconds and micro-seconds to calculate the time_low,
+     * time_mid, and time_high fields used by RFC 4122 version 1 UUIDs
+     *
+     * @param string $seconds
+     * @param string $microSeconds
+     * @return string[] An array containing `low`, `mid`, and `high` keys
+     * @link http://tools.ietf.org/html/rfc4122#section-4.2.2
+     */
     public function calculateTime($seconds, $microSeconds)
     {
         // 0x01b21dd213814000 is the number of 100-ns intervals between the

src/Converter/TimeConverterInterface.php

@@ -14,15 +14,20 @@
 
 namespace Ramsey\Uuid\Converter;
 
+/**
+ * TimeConverterInterface provides facilities for converting parts of time into
+ * representations that may be used in UUIDs
+ */
 interface TimeConverterInterface
 {
-
     /**
-     * Calculates low, mid, high time array.
+     * Uses the provided seconds and micro-seconds to calculate the time_low,
+     * time_mid, and time_high fields used by RFC 4122 version 1 UUIDs
      *
      * @param string $seconds
      * @param string $microSeconds
-     * @return string[] An array guaranteed to contain 'low', 'mid', and 'high' keys.
+     * @return string[] An array guaranteed to contain `low`, `mid`, and `high` keys
+     * @link http://tools.ietf.org/html/rfc4122#section-4.2.2
      */
     public function calculateTime($seconds, $microSeconds);
 }