Add docblocks for classes and interfaces in top-level Ramsey\Uuid namespace

src/BinaryUtils.php

@@ -2,11 +2,17 @@
 
 namespace Ramsey\Uuid;
 
+/**
+ * Provides binary math utilities
+ */
 class BinaryUtils
 {
     /**
+     * Applies the RFC 4122 variant field to the `clock_seq_hi_and_reserved` field
+     *
      * @param $clockSeqHi
-     * @return int
+     * @return int The high field of the clock sequence multiplexed with the variant
+     * @link http://tools.ietf.org/html/rfc4122#section-4.1.1
      */
     public static function applyVariant($clockSeqHi)
     {
@@ -19,9 +25,12 @@ class BinaryUtils
     }
 
     /**
+     * Applies the RFC 4122 version number to the `time_hi_and_version` field
+     *
      * @param string $timeHi
      * @param integer $version
-     * @return int|string
+     * @return int The high field of the timestamp multiplexed with the version number
+     * @link http://tools.ietf.org/html/rfc4122#section-4.1.3
      */
     public static function applyVersion($timeHi, $version)
     {

src/DegradedUuid.php

@@ -16,32 +16,20 @@ namespace Ramsey\Uuid;
 
 use Ramsey\Uuid\Converter\NumberConverterInterface;
 use Ramsey\Uuid\Codec\CodecInterface;
+use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
+use Ramsey\Uuid\Exception\UnsupportedOperationException;
 
+/**
+ * DegradedUuid represents an RFC 4122 UUID on 32-bit systems
+ *
+ * @see Uuid
+ */
 class DegradedUuid extends Uuid
 {
-
-    public function __construct(array $fields, NumberConverterInterface $converter, CodecInterface $codec)
-    {
-        parent::__construct($fields, $converter, $codec);
-    }
-
-    /**
-     * Returns a PHP DateTime object representing the timestamp associated
-     * with this UUID.
-     *
-     * The timestamp value is only meaningful in a time-based UUID, which
-     * has version type 1. If this UUID is not a time-based UUID then
-     * this method throws UnsupportedOperationException.
-     *
-     * @return \DateTime A PHP DateTime representation of the date
-     * @throws Exception\UnsupportedOperationException If this UUID is not a version 1 UUID
-     * @throws Exception\UnsatisfiedDependencyException if called on a 32-bit system and
-     *         Moontoast\Math\BigNumber is not present
-     */
     public function getDateTime()
     {
         if ($this->getVersion() != 1) {
-            throw new Exception\UnsupportedOperationException('Not a time-based UUID');
+            throw new UnsupportedOperationException('Not a time-based UUID');
         }
 
         $time = $this->converter->fromHex($this->getTimestampHex());
@@ -56,27 +44,14 @@ class DegradedUuid extends Uuid
     }
 
     /**
-     * Returns an array of the fields of this UUID, with keys named according
-     * to the RFC 4122 names for the fields.
+     * For degraded UUIDs, throws an `UnsatisfiedDependencyException` when
+     * called on a 32-bit system
      *
-     * * **time_low**: The low field of the timestamp, an unsigned 32-bit integer
-     * * **time_mid**: The middle field of the timestamp, an unsigned 16-bit integer
-     * * **time_hi_and_version**: The high field of the timestamp multiplexed with
-     *   the version number, an unsigned 16-bit integer
-     * * **clock_seq_hi_and_reserved**: The high field of the clock sequence
-     *   multiplexed with the variant, an unsigned 8-bit integer
-     * * **clock_seq_low**: The low field of the clock sequence, an unsigned
-     *   8-bit integer
-     * * **node**: The spatially unique node identifier, an unsigned 48-bit
-     *   integer
-     *
-     * @return array The UUID fields represented as integer values
-     * @throws Exception\UnsatisfiedDependencyException if called on a 32-bit system
-     * @link http://tools.ietf.org/html/rfc4122#section-4.1.2
+     * @throws UnsatisfiedDependencyException if called on a 32-bit system
      */
     public function getFields()
     {
-        throw new Exception\UnsatisfiedDependencyException(
+        throw new UnsatisfiedDependencyException(
             'Cannot call ' . __METHOD__ . ' on a 32-bit system, since some '
             . 'values overflow the system max integer value'
             . '; consider calling getFieldsHex instead'
@@ -84,33 +59,14 @@ class DegradedUuid extends Uuid
     }
 
     /**
-     * Returns the node value associated with this UUID
+     * For degraded UUIDs, throws an `UnsatisfiedDependencyException` when
+     * called on a 32-bit system
      *
-     * For UUID version 1, the node field consists of an IEEE 802 MAC
-     * address, usually the host address. For systems with multiple IEEE
-     * 802 addresses, any available one can be used. The lowest addressed
-     * octet (octet number 10) contains the global/local bit and the
-     * unicast/multicast bit, and is the first octet of the address
-     * transmitted on an 802.3 LAN.
-     *
-     * For systems with no IEEE address, a randomly or pseudo-randomly
-     * generated value may be used; see RFC 4122, Section 4.5. The
-     * multicast bit must be set in such addresses, in order that they
-     * will never conflict with addresses obtained from network cards.
-     *
-     * For UUID version 3 or 5, the node field is a 48-bit value constructed
-     * from a name as described in RFC 4122, Section 4.3.
-     *
-     * For UUID version 4, the node field is a randomly or pseudo-randomly
-     * generated 48-bit value as described in RFC 4122, Section 4.4.
-     *
-     * @return int Unsigned 48-bit integer value of node
-     * @link http://tools.ietf.org/html/rfc4122#section-4.1.6
-     * @throws Exception\UnsatisfiedDependencyException if called on a 32-bit system
+     * @throws UnsatisfiedDependencyException if called on a 32-bit system
      */
     public function getNode()
     {
-        throw new Exception\UnsatisfiedDependencyException(
+        throw new UnsatisfiedDependencyException(
             'Cannot call ' . __METHOD__ . ' on a 32-bit system, since node '
             . 'is an unsigned 48-bit integer and can overflow the system '
             . 'max integer value'
@@ -119,14 +75,14 @@ class DegradedUuid extends Uuid
     }
 
     /**
-     * Returns the low field of the timestamp (the first 32 bits of the UUID).
+     * For degraded UUIDs, throws an `UnsatisfiedDependencyException` when
+     * called on a 32-bit system
      *
-     * @return int Unsigned 32-bit integer value of time_low
-     * @throws Exception\UnsatisfiedDependencyException if called on a 32-bit system
+     * @throws UnsatisfiedDependencyException if called on a 32-bit system
      */
     public function getTimeLow()
     {
-        throw new Exception\UnsatisfiedDependencyException(
+        throw new UnsatisfiedDependencyException(
             'Cannot call ' . __METHOD__ . ' on a 32-bit system, since time_low '
             . 'is an unsigned 32-bit integer and can overflow the system '
             . 'max integer value'
@@ -135,29 +91,19 @@ class DegradedUuid extends Uuid
     }
 
     /**
-     * The timestamp value associated with this UUID
+     * For degraded UUIDs, throws an `UnsatisfiedDependencyException` when
+     * called on a 32-bit system
      *
-     * The 60 bit timestamp value is constructed from the time_low,
-     * time_mid, and time_hi fields of this UUID. The resulting
-     * timestamp is measured in 100-nanosecond units since midnight,
-     * October 15, 1582 UTC.
-     *
-     * The timestamp value is only meaningful in a time-based UUID, which
-     * has version type 1. If this UUID is not a time-based UUID then
-     * this method throws UnsupportedOperationException.
-     *
-     * @return int Unsigned 60-bit integer value of the timestamp
-     * @throws Exception\UnsupportedOperationException If this UUID is not a version 1 UUID
-     * @throws Exception\UnsatisfiedDependencyException if called on a 32-bit system
-     * @link http://tools.ietf.org/html/rfc4122#section-4.1.4
+     * @throws UnsatisfiedDependencyException if called on a 32-bit system
+     * @throws UnsupportedOperationException If this UUID is not a version 1 UUID
      */
     public function getTimestamp()
     {
         if ($this->getVersion() != 1) {
-            throw new Exception\UnsupportedOperationException('Not a time-based UUID');
+            throw new UnsupportedOperationException('Not a time-based UUID');
         }
 
-        throw new Exception\UnsatisfiedDependencyException(
+        throw new UnsatisfiedDependencyException(
             'Cannot call ' . __METHOD__ . ' on a 32-bit system, since timestamp '
             . 'is an unsigned 60-bit integer and can overflow the system '
             . 'max integer value'

src/FeatureSet.php

@@ -19,49 +19,96 @@ use Ramsey\Uuid\Generator\PeclUuidTimeGenerator;
 use Ramsey\Uuid\Provider\Node\FallbackNodeProvider;
 use Ramsey\Uuid\Provider\Node\RandomNodeProvider;
 use Ramsey\Uuid\Provider\Node\SystemNodeProvider;
+use Ramsey\Uuid\Converter\NumberConverterInterface;
 use Ramsey\Uuid\Converter\Number\BigNumberConverter;
 use Ramsey\Uuid\Converter\Number\DegradedNumberConverter;
 use Ramsey\Uuid\Converter\Time\BigNumberTimeConverter;
 use Ramsey\Uuid\Converter\Time\DegradedTimeConverter;
 use Ramsey\Uuid\Converter\Time\PhpTimeConverter;
 use Ramsey\Uuid\Provider\Time\SystemTimeProvider;
+use Ramsey\Uuid\Builder\UuidBuilderInterface;
 use Ramsey\Uuid\Builder\DefaultUuidBuilder;
+use Ramsey\Uuid\Codec\CodecInterface;
 use Ramsey\Uuid\Codec\StringCodec;
 use Ramsey\Uuid\Codec\GuidStringCodec;
 use Ramsey\Uuid\Builder\DegradedUuidBuilder;
 use Ramsey\Uuid\Generator\RandomGeneratorFactory;
+use Ramsey\Uuid\Generator\RandomGeneratorInterface;
 use Ramsey\Uuid\Generator\TimeGeneratorFactory;
+use Ramsey\Uuid\Generator\TimeGeneratorInterface;
 use Ramsey\Uuid\Provider\TimeProviderInterface;
+use Ramsey\Uuid\Provider\NodeProviderInterface;
 
 /**
- * Detects and exposes available features in current environment (32 or 64 bit, available dependencies...)
- *
- * @author thibaud
- *
+ * FeatureSet detects and exposes available features in the current environment
+ * (32- or 64-bit, available dependencies, etc.)
  */
 class FeatureSet
 {
-
+    /**
+     * @var bool
+     */
     private $disableBigNumber = false;
 
+    /**
+     * @var bool
+     */
     private $disable64Bit = false;
 
+    /**
+     * @var bool
+     */
     private $ignoreSystemNode = false;
 
+    /**
+     * @var bool
+     */
     private $enablePecl = false;
 
+    /**
+     * @var UuidBuilderInterface
+     */
     private $builder;
 
+    /**
+     * @var CodecInterface
+     */
     private $codec;
 
+    /**
+     * @var NodeProviderInterface
+     */
     private $nodeProvider;
 
+    /**
+     * @var NumberConverterInterface
+     */
     private $numberConverter;
 
+    /**
+     * @var RandomGeneratorInterface
+     */
     private $randomGenerator;
 
+    /**
+     * @var TimeGeneratorInterface
+     */
     private $timeGenerator;
 
+    /**
+     * Constructs a `FeatureSet` for use by a `UuidFactory` to determine or set
+     * features available to the environment
+     *
+     * @param bool $useGuids Whether to build UUIDs using the `GuidStringCodec`
+     * @param bool $force32Bit Whether to force the use of 32-bit functionality
+     *     (primarily for testing purposes)
+     * @param bool $forceNoBigNumber Whether to disable the use of moontoast/math
+     *     `BigNumber` (primarily for testing purposes)
+     * @param bool $ignoreSystemNode Whether to disable attempts to check for
+     *     the system host ID (primarily for testing purposes)
+     * @param bool $enablePecl Whether to enable the use of the `PeclUuidTimeGenerator`
+     *     to generate version 1 UUIDs
+     */
     public function __construct(
         $useGuids = false,
         $force32Bit = false,
@@ -82,41 +129,83 @@ class FeatureSet
         $this->setTimeProvider(new SystemTimeProvider());
     }
 
+    /**
+     * Returns the builder configured for this environment
+     *
+     * @return UuidBuilderInterface
+     */
     public function getBuilder()
     {
         return $this->builder;
     }
 
+    /**
+     * Returns the UUID UUID coder-decoder configured for this environment
+     *
+     * @return CodecInterface
+     */
     public function getCodec()
     {
         return $this->codec;
     }
 
+    /**
+     * Returns the system node ID provider configured for this environment
+     *
+     * @return NodeProviderInterface
+     */
     public function getNodeProvider()
     {
         return $this->nodeProvider;
     }
 
+    /**
+     * Returns the number converter configured for this environment
+     *
+     * @return NumberConverterInterface
+     */
     public function getNumberConverter()
     {
         return $this->numberConverter;
     }
 
+    /**
+     * Returns the random UUID generator configured for this environment
+     *
+     * @return RandomGeneratorInterface
+     */
     public function getRandomGenerator()
     {
         return $this->randomGenerator;
     }
 
+    /**
+     * Returns the time-based UUID generator configured for this environment
+     *
+     * @return TimeGeneratorInterface
+     */
     public function getTimeGenerator()
     {
         return $this->timeGenerator;
     }
 
+    /**
+     * Sets the time provider for use in this environment
+     *
+     * @param TimeProviderInterface $timeProvider
+     */
     public function setTimeProvider(TimeProviderInterface $timeProvider)
     {
         $this->timeGenerator = $this->buildTimeGenerator($timeProvider);
     }
 
+    /**
+     * Determines which UUID coder-decoder to use and returns the configured
+     * codec for this environment
+     *
+     * @param bool $useGuids Whether to build UUIDs using the `GuidStringCodec`
+     * @return CodecInterface
+     */
     protected function buildCodec($useGuids = false)
     {
         if ($useGuids) {
@@ -126,6 +215,12 @@ class FeatureSet
         return new StringCodec($this->builder);
     }
 
+    /**
+     * Determines which system node ID provider to use and returns the configured
+     * system node ID provider for this environment
+     *
+     * @return NodeProviderInterface
+     */
     protected function buildNodeProvider()
     {
         if ($this->ignoreSystemNode) {
@@ -138,6 +233,12 @@ class FeatureSet
         ]);
     }
 
+    /**
+     * Determines which number converter to use and returns the configured
+     * number converter for this environment
+     *
+     * @return NumberConverterInterface
+     */
     protected function buildNumberConverter()
     {
         if ($this->hasBigNumber()) {
@@ -147,11 +248,23 @@ class FeatureSet
         return new DegradedNumberConverter();
     }
 
+    /**
+     * Determines which random UUID generator to use and returns the configured
+     * random UUID generator for this environment
+     *
+     * @return RandomGeneratorInterface
+     */
     protected function buildRandomGenerator()
     {
         return (new RandomGeneratorFactory())->getGenerator();
     }
 
+    /**
+     * Determines which time-based UUID generator to use and returns the configured
+     * time-based UUID generator for this environment
+     *
+     * @return TimeGeneratorInterface
+     */
     protected function buildTimeGenerator(TimeProviderInterface $timeProvider)
     {
         if ($this->enablePecl) {
@@ -165,6 +278,12 @@ class FeatureSet
         ))->getGenerator();
     }
 
+    /**
+     * Determines which time converter to use and returns the configured
+     * time converter for this environment
+     *
+     * @return TimeConverterInterface
+     */
     protected function buildTimeConverter()
     {
         if ($this->is64BitSystem()) {
@@ -176,6 +295,12 @@ class FeatureSet
         return new DegradedTimeConverter();
     }
 
+    /**
+     * Determines which UUID builder to use and returns the configured UUID
+     * builder for this environment
+     *
+     * @return UuidBuilderInterface
+     */
     protected function buildUuidBuilder()
     {
         if ($this->is64BitSystem()) {
@@ -186,7 +311,7 @@ class FeatureSet
     }
 
     /**
-     * Returns true if the system has Moontoast\Math\BigNumber
+     * Returns true if the system has `Moontoast\Math\BigNumber`
      *
      * @return bool
      */

src/Uuid.php

@@ -35,7 +35,6 @@ use Ramsey\Uuid\Exception\UnsupportedOperationException;
  * @link http://docs.python.org/3/library/uuid.html
  * @link http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html
  */
-
 class Uuid implements UuidInterface
 {
     /**
@@ -115,7 +114,7 @@ class Uuid implements UuidInterface
      * This is initialized to the nil value.
      *
      * @var array
-     * @see self::getFields()
+     * @see UuidInterface::getFieldsHex()
      */
     protected $fields = array(
         'time_low' => '00000000',
@@ -149,14 +148,17 @@ class Uuid implements UuidInterface
      * ```
      *
      * @param array $fields An array of fields from which to construct a UUID;
-     *     see {@see \Ramsey\Uuid\Uuid::getFields()} for array structure.
+     *     see {@see \Ramsey\Uuid\UuidInterface::getFieldsHex()} for array structure.
      * @param NumberConverterInterface $converter The number converter to use
      *     for converting hex values to/from integers.
      * @param CodecInterface $codec The codec to use when encoding or decoding
      *     UUID strings.
      */
-    public function __construct(array $fields, NumberConverterInterface $converter, CodecInterface $codec)
-    {
+    public function __construct(
+        array $fields,
+        NumberConverterInterface $converter,
+        CodecInterface $codec
+    ) {
         $this->fields = $fields;
         $this->codec = $codec;
         $this->converter = $converter;
@@ -176,7 +178,7 @@ class Uuid implements UuidInterface
 
     /**
      * Converts this UUID object to a string when the object is serialized
-     * with json_encode()
+     * with `json_encode()`
      *
      * @return string
      * @link http://php.net/manual/en/class.jsonserializable.php
@@ -186,19 +188,6 @@ class Uuid implements UuidInterface
         return $this->toString();
     }
 
-    /**
-     * Compares this UUID to the specified UUID.
-     *
-     * The first of two UUIDs is greater than the second if the most
-     * significant field in which the UUIDs differ is greater for the first
-     * UUID.
-     *
-     * Q. What's the value of being able to sort UUIDs?<br>
-     * A. Use them as keys in a B-Tree or similar mapping.
-     *
-     * @param UuidInterface $uuid UUID to which this UUID is compared
-     * @return int -1, 0 or 1 as this UUID is less than, equal to, or greater than `$uuid`
-     */
     public function compareTo(UuidInterface $uuid)
     {
         $comparison = 0;
@@ -216,16 +205,6 @@ class Uuid implements UuidInterface
         return $comparison;
     }
 
-    /**
-     * Compares this object to the specified object.
-     *
-     * The result is true if and only if the argument is not null, is a UUID
-     * object, has the same variant, and contains the same value, bit for bit,
-     * as this UUID.
-     *
-     * @param object $obj
-     * @return bool True if `$obj` is equal to this UUID
-     */
     public function equals($obj)
     {
         if (!($obj instanceof UuidInterface)) {
@@ -235,12 +214,6 @@ class Uuid implements UuidInterface
         return ($this->compareTo($obj) == 0);
     }
 
-    /**
-     * Returns the UUID as a 16-byte string (containing the six integer fields
-     * in big-endian byte order).
-     *
-     * @return string
-     */
     public function getBytes()
     {
         return $this->codec->encodeBinary($this);
@@ -257,12 +230,6 @@ class Uuid implements UuidInterface
         return hexdec($this->getClockSeqHiAndReservedHex());
     }
 
-    /**
-     * Returns the high field of the clock sequence multiplexed with the variant
-     * (bits 65-72 of the UUID).
-     *
-     * @return string Hexadecimal value of clock_seq_hi_and_reserved
-     */
     public function getClockSeqHiAndReservedHex()
     {
         return $this->fields['clock_seq_hi_and_reserved'];
@@ -278,11 +245,6 @@ class Uuid implements UuidInterface
         return hexdec($this->getClockSeqLowHex());
     }
 
-    /**
-     * Returns the low field of the clock sequence (bits 73-80 of the UUID).
-     *
-     * @return string Hexadecimal value of clock_seq_low
-     */
     public function getClockSeqLowHex()
     {
         return $this->fields['clock_seq_low'];
@@ -310,37 +272,16 @@ class Uuid implements UuidInterface
             | $this->getClockSeqLow();
     }
 
-    /**
-     * Returns the clock sequence value associated with this UUID.
-     *
-     * @return string Hexadecimal value of clock sequence
-     */
     public function getClockSequenceHex()
     {
         return sprintf('%04x', $this->getClockSequence());
     }
 
-    /**
-     * Returns the number converter to use for converting hex values to/from integers.
-     *
-     * @return NumberConverterInterface
-     */
     public function getNumberConverter()
     {
         return $this->converter;
     }
 
-    /**
-     * Returns a PHP `DateTime` object representing the timestamp associated
-     * with this UUID.
-     *
-     * The timestamp value is only meaningful in a time-based UUID, which
-     * has version type 1. If this UUID is not a time-based UUID then
-     * this method throws `UnsupportedOperationException`.
-     *
-     * @return \DateTime A PHP DateTime representation of the date
-     * @throws UnsupportedOperationException If this UUID is not a version 1 UUID
-     */
     public function getDateTime()
     {
         if ($this->getVersion() != 1) {
@@ -383,44 +324,16 @@ class Uuid implements UuidInterface
         );
     }
 
-    /**
-     * Returns an array of the fields of this UUID, with keys named according
-     * to the RFC 4122 names for the fields.
-     *
-     * * **time_low**: The low field of the timestamp, an unsigned 32-bit integer
-     * * **time_mid**: The middle field of the timestamp, an unsigned 16-bit integer
-     * * **time_hi_and_version**: The high field of the timestamp multiplexed with
-     *   the version number, an unsigned 16-bit integer
-     * * **clock_seq_hi_and_reserved**: The high field of the clock sequence
-     *   multiplexed with the variant, an unsigned 8-bit integer
-     * * **clock_seq_low**: The low field of the clock sequence, an unsigned
-     *   8-bit integer
-     * * **node**: The spatially unique node identifier, an unsigned 48-bit
-     *   integer
-     *
-     * @return array The UUID fields represented as hexadecimal values
-     */
     public function getFieldsHex()
     {
         return $this->fields;
     }
 
-    /**
-     * Returns the hexadecimal value of the UUID.
-     *
-     * @return string
-     */
     public function getHex()
     {
         return str_replace('-', '', $this->toString());
     }
 
-    /**
-     * Returns the integer value of the UUID, converted to an appropriate number
-     * representation.
-     *
-     * @return mixed Converted representation of the unsigned 128-bit integer value
-     */
     public function getInteger()
     {
         return $this->converter->fromHex($this->getHex());
@@ -436,11 +349,6 @@ class Uuid implements UuidInterface
         return $this->converter->fromHex($this->getLeastSignificantBitsHex());
     }
 
-    /**
-     * Returns the least significant 64 bits of this UUID's 128 bit value.
-     *
-     * @return string Hexadecimal value of least significant bits
-     */
     public function getLeastSignificantBitsHex()
     {
         return sprintf(
@@ -461,11 +369,6 @@ class Uuid implements UuidInterface
         return $this->converter->fromHex($this->getMostSignificantBitsHex());
     }
 
-    /**
-     * Returns the most significant 64 bits of this UUID's 128 bit value.
-     *
-     * @return string Hexadecimal value of most significant bits
-     */
     public function getMostSignificantBitsHex()
     {
         return sprintf(
@@ -505,30 +408,6 @@ class Uuid implements UuidInterface
         return hexdec($this->getNodeHex());
     }
 
-    /**
-     * Returns the node value associated with this UUID
-     *
-     * For UUID version 1, the node field consists of an IEEE 802 MAC
-     * address, usually the host address. For systems with multiple IEEE
-     * 802 addresses, any available one can be used. The lowest addressed
-     * octet (octet number 10) contains the global/local bit and the
-     * unicast/multicast bit, and is the first octet of the address
-     * transmitted on an 802.3 LAN.
-     *
-     * For systems with no IEEE address, a randomly or pseudo-randomly
-     * generated value may be used; see RFC 4122, Section 4.5. The
-     * multicast bit must be set in such addresses, in order that they
-     * will never conflict with addresses obtained from network cards.
-     *
-     * For UUID version 3 or 5, the node field is a 48-bit value constructed
-     * from a name as described in RFC 4122, Section 4.3.
-     *
-     * For UUID version 4, the node field is a randomly or pseudo-randomly
-     * generated 48-bit value as described in RFC 4122, Section 4.4.
-     *
-     * @return string Hexadecimal value of node
-     * @link http://tools.ietf.org/html/rfc4122#section-4.1.6
-     */
     public function getNodeHex()
     {
         return $this->fields['node'];
@@ -545,12 +424,6 @@ class Uuid implements UuidInterface
         return hexdec($this->getTimeHiAndVersionHex());
     }
 
-    /**
-     * Returns the high field of the timestamp multiplexed with the version
-     * number (bits 49-64 of the UUID).
-     *
-     * @return string Hexadecimal value of time_hi_and_version
-     */
     public function getTimeHiAndVersionHex()
     {
         return $this->fields['time_hi_and_version'];
@@ -566,11 +439,6 @@ class Uuid implements UuidInterface
         return hexdec($this->getTimeLowHex());
     }
 
-    /**
-     * Returns the low field of the timestamp (the first 32 bits of the UUID).
-     *
-     * @return string Hexadecimal value of time_low
-     */
     public function getTimeLowHex()
     {
         return $this->fields['time_low'];
@@ -586,11 +454,6 @@ class Uuid implements UuidInterface
         return hexdec($this->getTimeMidHex());
     }
 
-    /**
-     * Returns the middle field of the timestamp (bits 33-48 of the UUID).
-     *
-     * @return string Hexadecimal value of time_mid
-     */
     public function getTimeMidHex()
     {
         return $this->fields['time_mid'];
@@ -621,22 +484,6 @@ class Uuid implements UuidInterface
         return hexdec($this->getTimestampHex());
     }
 
-    /**
-     * Returns the timestamp value associated with this UUID.
-     *
-     * The 60 bit timestamp value is constructed from the time_low,
-     * time_mid, and time_hi fields of this UUID. The resulting
-     * timestamp is measured in 100-nanosecond units since midnight,
-     * October 15, 1582 UTC.
-     *
-     * The timestamp value is only meaningful in a time-based UUID, which
-     * has version type 1. If this UUID is not a time-based UUID then
-     * this method throws UnsupportedOperationException.
-     *
-     * @return string Hexadecimal value of the timestamp
-     * @throws UnsupportedOperationException If this UUID is not a version 1 UUID
-     * @link http://tools.ietf.org/html/rfc4122#section-4.1.4
-     */
     public function getTimestampHex()
     {
         if ($this->getVersion() != 1) {
@@ -651,31 +498,11 @@ class Uuid implements UuidInterface
         );
     }
 
-    /**
-     * Returns the string representation of the UUID as a URN.
-     *
-     * @return string
-     * @link http://en.wikipedia.org/wiki/Uniform_Resource_Name
-     */
     public function getUrn()
     {
         return 'urn:uuid:' . $this->toString();
     }
 
-    /**
-     * Returns the variant number associated with this UUID.
-     *
-     * The variant number describes the layout of the UUID. The variant
-     * number has the following meaning:
-     *
-     * * 0 - Reserved for NCS backward compatibility
-     * * 2 - The RFC 4122 variant (used by this class)
-     * * 6 - Reserved, Microsoft Corporation backward compatibility
-     * * 7 - Reserved for future definition
-     *
-     * @return int
-     * @link http://tools.ietf.org/html/rfc4122#section-4.1.1
-     */
     public function getVariant()
     {
         $clockSeq = $this->getClockSeqHiAndReserved();
@@ -692,24 +519,6 @@ class Uuid implements UuidInterface
         return $variant;
     }
 
-    /**
-     * Returns the version number associated with this UUID.
-     *
-     * The version number describes how this UUID was generated and has the
-     * following meaning:
-     *
-     * * 1 - Time-based UUID
-     * * 2 - DCE security UUID
-     * * 3 - Name-based UUID hashed with MD5
-     * * 4 - Randomly generated UUID
-     * * 5 - Name-based UUID hashed with SHA-1
-     *
-     * Returns null if this UUID is not an RFC 4122 variant, since version
-     * is only meaningful for this variant.
-     *
-     * @return int|null
-     * @link http://tools.ietf.org/html/rfc4122#section-4.1.3
-     */
     public function getVersion()
     {
         if ($this->getVariant() == self::RFC_4122) {
@@ -719,11 +528,6 @@ class Uuid implements UuidInterface
         return null;
     }
 
-    /**
-     * Converts this UUID into a string representation.
-     *
-     * @return string
-     */
     public function toString()
     {
         return $this->codec->encode($this);
@@ -787,7 +591,7 @@ class Uuid implements UuidInterface
     }
 
     /**
-     * Check if a string is a valid uuid.
+     * Check if a string is a valid UUID.
      *
      * @param string $uuid The string UUID to test
      * @return boolean
@@ -810,10 +614,6 @@ class Uuid implements UuidInterface
     /**
      * Generate a version 1 UUID from a host ID, sequence number, and the current time.
      *
-     * If $node is not given, we will attempt to obtain the local hardware
-     * address. If $clockSeq is given, it is used as the sequence number;
-     * otherwise a random 14-bit sequence number is chosen.
-     *
      * @param int|string $node A 48-bit number representing the hardware address
      *     This number may be represented as an integer or a hexadecimal string.
      * @param int $clockSeq A 14-bit number used to help avoid duplicates that

src/UuidFactory.php

@@ -21,24 +21,21 @@ use Ramsey\Uuid\Generator\RandomGeneratorInterface;
 use Ramsey\Uuid\Generator\TimeGeneratorInterface;
 use Ramsey\Uuid\Codec\CodecInterface;
 use Ramsey\Uuid\Builder\UuidBuilderInterface;
+use Ramsey\Uuid\UuidInterface;
 
 class UuidFactory implements UuidFactoryInterface
 {
-
     /**
-     *
      * @var CodecInterface
      */
     private $codec = null;
 
     /**
-     *
      * @var NodeProviderInterface
      */
     private $nodeProvider = null;
 
     /**
-     *
      * @var NumberConverterInterface
      */
     private $numberConverter = null;
@@ -54,14 +51,14 @@ class UuidFactory implements UuidFactoryInterface
     private $timeGenerator = null;
 
     /**
-     *
      * @var UuidBuilderInterface
      */
     private $uuidBuilder = null;
 
     /**
-     * Create a new a instance
-     * @param FeatureSet $features
+     * Constructs a `UuidFactory` for creating `Ramsey\Uuid\UuidInterface` instances
+     *
+     * @param FeatureSet $features A set of features for use when creating UUIDs
      */
     public function __construct(FeatureSet $features = null)
     {
@@ -75,74 +72,104 @@ class UuidFactory implements UuidFactoryInterface
         $this->uuidBuilder = $features->getBuilder();
     }
 
+    /**
+     * Returns the UUID coder-decoder used by this factory
+     *
+     * @return CodecInterface
+     */
     public function getCodec()
     {
         return $this->codec;
     }
 
+    /**
+     * Returns the system node ID provider used by this factory
+     *
+     * @return NodeProviderInterface
+     */
     public function getNodeProvider()
     {
         return $this->nodeProvider;
     }
 
+    /**
+     * Returns the random UUID generator used by this factory
+     *
+     * @return RandomGeneratorInterface
+     */
     public function getRandomGenerator()
     {
         return $this->randomGenerator;
     }
 
+    /**
+     * Returns the time-based UUID generator used by this factory
+     *
+     * @return TimeGeneratorInterface
+     */
     public function getTimeGenerator()
     {
         return $this->timeGenerator;
     }
 
+    /**
+     * Sets the time-based UUID generator this factory will use to generate version 1 UUIDs
+     *
+     * @param TimeGeneratorInterface $generator
+     */
     public function setTimeGenerator(TimeGeneratorInterface $generator)
     {
         $this->timeGenerator = $generator;
     }
 
+    /**
+     * Returns the number converter used by this factory
+     *
+     * @return NumberConverterInterface
+     */
     public function getNumberConverter()
     {
         return $this->numberConverter;
     }
 
+    /**
+     * Sets the random UUID generator this factory will use to generate version 4 UUIDs
+     *
+     * @param RandomGeneratorInterface $generator
+     */
     public function setRandomGenerator(RandomGeneratorInterface $generator)
     {
         $this->randomGenerator = $generator;
     }
 
+    /**
+     * Sets the number converter this factory will use
+     *
+     * @param NumberConverterInterface $converter
+     */
     public function setNumberConverter(NumberConverterInterface $converter)
     {
         $this->numberConverter = $converter;
     }
 
+    /**
+     * Sets the UUID builder this factory will use when creating `Uuid` instances
+     *
+     * @param UuidBuilderInterface $builder
+     */
     public function setUuidBuilder(UuidBuilderInterface $builder)
     {
         $this->uuidBuilder = $builder;
     }
 
-    /**
-     * Creates a UUID from a byte string.
-     *
-     * @param string $bytes
-     * @return Uuid
-     * @throws InvalidArgumentException If the $bytes string does not contain 16 characters
-     */
     public function fromBytes($bytes)
     {
         return $this->codec->decodeBytes($bytes);
     }
 
-    /**
-     * Creates a UUID from the string standard representation as described
-     * in the toString() method.
-     *
-     * @param string $name A string that specifies a UUID
-     * @return Uuid
-     * @throws InvalidArgumentException If the $name isn't a valid UUID
-     */
-    public function fromString($name)
+    public function fromString($uuid)
     {
-        return $this->codec->decode($name);
+        return $this->codec->decode($uuid);
     }
 
     public function fromInteger($integer)
@@ -153,21 +180,6 @@ class UuidFactory implements UuidFactoryInterface
         return $this->fromString($hex);
     }
 
-    /**
-     * Generate a version 1 UUID from a host ID, sequence number, and the current time.
-     * If $node is not given, we will attempt to obtain the local hardware
-     * address. If $clockSeq is given, it is used as the sequence number;
-     * otherwise a random 14-bit sequence number is chosen.
-     *
-     * @param int|string $node A 48-bit number representing the hardware
-     *                         address. This number may be represented as
-     *                         an integer or a hexadecimal string.
-     * @param int $clockSeq A 14-bit number used to help avoid duplicates that
-     *                      could arise when the clock is set backwards in time
-     *                      or if the node ID changes.
-     * @return Uuid
-     * @throws InvalidArgumentException if the $node is invalid
-     */
     public function uuid1($node = null, $clockSeq = null)
     {
         $bytes = $this->timeGenerator->generate($node, $clockSeq);
@@ -176,25 +188,11 @@ class UuidFactory implements UuidFactoryInterface
         return $this->uuidFromHashedName($hex, 1);
     }
 
-
-    /**
-     * Generate a version 3 UUID based on the MD5 hash of a namespace identifier (which
-     * is a UUID) and a name (which is a string).
-     *
-     * @param Uuid|string $ns The UUID namespace in which to create the named UUID
-     * @param string $name The name to create a UUID for
-     * @return Uuid
-     */
     public function uuid3($ns, $name)
     {
         return $this->uuidFromNsAndName($ns, $name, 3, 'md5');
     }
 
-    /**
-     * Generate a version 4 (random) UUID.
-     *
-     * @return Uuid
-     */
     public function uuid4()
     {
         $bytes = $this->randomGenerator->generate(16);
@@ -207,32 +205,39 @@ class UuidFactory implements UuidFactoryInterface
         return $this->uuidFromHashedName($hex, 4);
     }
 
-    /**
-     * Generate a version 5 UUID based on the SHA-1 hash of a namespace identifier (which
-     * is a UUID) and a name (which is a string).
-     *
-     * @param Uuid|string $ns The UUID namespace in which to create the named UUID
-     * @param string $name The name to create a UUID for
-     * @return Uuid
-     */
     public function uuid5($ns, $name)
     {
         return $this->uuidFromNsAndName($ns, $name, 5, 'sha1');
     }
 
+    /**
+     * Returns a `Uuid`
+     *
+     * Uses the configured builder and codec and the provided array of hexadecimal
+     * value UUID fields to construct a `Uuid` object.
+     *
+     * @param array $fields An array of fields from which to construct a UUID;
+     *     see {@see \Ramsey\Uuid\UuidInterface::getFieldsHex()} for array structure.
+     * @return UuidInterface
+     */
     public function uuid(array $fields)
     {
         return $this->uuidBuilder->build($this->codec, $fields);
     }
 
     /**
-     * @param string $name
-     * @param integer $version
-     * @param string $hashFunction
+     * Returns a version 3 or 5 namespaced `Uuid`
+     *
+     * @param string|UuidInterface $ns The UUID namespace to use
+     * @param string $name The string to hash together with the namespace
+     * @param int $version The version of UUID to create (3 or 5)
+     * @param string $hashFunction The hash function to use when hashing together
+     *     the namespace and name
+     * @return UuidInterface
      */
     protected function uuidFromNsAndName($ns, $name, $version, $hashFunction)
     {
-        if (!($ns instanceof Uuid)) {
+        if (!($ns instanceof UuidInterface)) {
             $ns = $this->codec->decode($ns);
         }
 
@@ -242,12 +247,12 @@ class UuidFactory implements UuidFactoryInterface
     }
 
     /**
-     * Returns a version 3 or 5 UUID based on the hash (md5 or sha1) of a
-     * namespace identifier (which is a UUID) and a name (which is a string)
+     * Returns a `Uuid` created from `$hash` with the version field set to `$version`
+     * and the variant field set for RFC 4122
      *
      * @param string $hash The hash to use when creating the UUID
-     * @param int $version The UUID version to be generated
-     * @return Uuid
+     * @param int $version The UUID version to set for this hash (1, 3, 4, or 5)
+     * @return UuidInterface
      */
     protected function uuidFromHashedName($hash, $version)
     {

src/UuidFactoryInterface.php

@@ -14,19 +14,76 @@
 
 namespace Ramsey\Uuid;
 
+/**
+ * UuidFactoryInterface defines common functionality all `UuidFactory` instances
+ * must implement
+ */
 interface UuidFactoryInterface
 {
+    /**
+     * Generate a version 1 UUID from a host ID, sequence number, and the current time.
+     *
+     * @param int|string $node A 48-bit number representing the hardware address
+     *     This number may be represented as an integer or a hexadecimal string.
+     * @param int $clockSeq A 14-bit number used to help avoid duplicates that
+     *     could arise when the clock is set backwards in time or if the node ID
+     *     changes.
+     * @return UuidInterface
+     */
     public function uuid1($node = null, $clockSeq = null);
 
+    /**
+     * Generate a version 3 UUID based on the MD5 hash of a namespace identifier
+     * (which is a UUID) and a name (which is a string).
+     *
+     * @param string $ns The UUID namespace in which to create the named UUID
+     * @param string $name The name to create a UUID for
+     * @return UuidInterface
+     */
     public function uuid3($ns, $name);
 
+    /**
+     * Generate a version 4 (random) UUID.
+     *
+     * @return UuidInterface
+     */
     public function uuid4();
 
+    /**
+     * Generate a version 5 UUID based on the SHA-1 hash of a namespace
+     * identifier (which is a UUID) and a name (which is a string).
+     *
+     * @param string $ns The UUID namespace in which to create the named UUID
+     * @param string $name The name to create a UUID for
+     * @return UuidInterface
+     */
     public function uuid5($ns, $name);
 
+    /**
+     * Creates a UUID from a byte string.
+     *
+     * @param string $bytes A 16-byte string representation of a UUID
+     * @return UuidInterface
+     */
     public function fromBytes($bytes);
 
-    public function fromString($name);
+    /**
+     * Creates a UUID from the string standard representation
+     *
+     * @param string $uuid A string representation of a UUID
+     * @return UuidInterface
+     */
+    public function fromString($uuid);
 
+    /**
+     * Creates a `Uuid` from an integer representation
+     *
+     * The integer representation may be a real integer, a string integer, or
+     * an integer representation supported by a configured number converter.
+     *
+     * @param mixed $integer The integer to use when creating a `Uuid` from an
+     *     integer; may be of any type understood by the configured number converter
+     * @return UuidInterface
+     */
     public function fromInteger($integer);
 }

src/UuidInterface.php

@@ -16,107 +16,250 @@ namespace Ramsey\Uuid;
 
 use Ramsey\Uuid\Converter\NumberConverterInterface;
 
+/**
+ * UuidInterface defines common functionality for all universally unique
+ * identifiers (UUIDs)
+ */
 interface UuidInterface extends \JsonSerializable
 {
-
     /**
-     * @return integer
+     * Compares this UUID to the specified UUID.
+     *
+     * The first of two UUIDs is greater than the second if the most
+     * significant field in which the UUIDs differ is greater for the first
+     * UUID.
+     *
+     * * Q. What's the value of being able to sort UUIDs?
+     * * A. Use them as keys in a B-Tree or similar mapping.
+     *
+     * @param UuidInterface $uuid UUID to which this UUID is compared
+     * @return int -1, 0 or 1 as this UUID is less than, equal to, or greater than `$uuid`
      */
     public function compareTo(UuidInterface $other);
 
     /**
-     * @return boolean
+     * Compares this object to the specified object.
+     *
+     * The result is true if and only if the argument is not null, is a UUID
+     * object, has the same variant, and contains the same value, bit for bit,
+     * as this UUID.
+     *
+     * @param object $obj
+     * @return bool True if `$obj` is equal to this UUID
      */
     public function equals($other);
 
     /**
+     * Returns the UUID as a 16-byte string (containing the six integer fields
+     * in big-endian byte order).
+     *
+     * @return string
+     */
+    public function getBytes();
+
+    /**
+     * Returns the number converter to use for converting hex values to/from integers.
+     *
      * @return NumberConverterInterface
      */
     public function getNumberConverter();
 
     /**
+     * Returns the hexadecimal value of the UUID.
+     *
      * @return string
      */
     public function getHex();
 
+    /**
+     * Returns an array of the fields of this UUID, with keys named according
+     * to the RFC 4122 names for the fields.
+     *
+     * * **time_low**: The low field of the timestamp, an unsigned 32-bit integer
+     * * **time_mid**: The middle field of the timestamp, an unsigned 16-bit integer
+     * * **time_hi_and_version**: The high field of the timestamp multiplexed with
+     *   the version number, an unsigned 16-bit integer
+     * * **clock_seq_hi_and_reserved**: The high field of the clock sequence
+     *   multiplexed with the variant, an unsigned 8-bit integer
+     * * **clock_seq_low**: The low field of the clock sequence, an unsigned
+     *   8-bit integer
+     * * **node**: The spatially unique node identifier, an unsigned 48-bit
+     *   integer
+     *
+     * @return array The UUID fields represented as hexadecimal values
+     */
     public function getFieldsHex();
 
     /**
-     * @return string
+     * Returns the high field of the clock sequence multiplexed with the variant
+     * (bits 65-72 of the UUID).
+     *
+     * @return string Hexadecimal value of clock_seq_hi_and_reserved
      */
     public function getClockSeqHiAndReservedHex();
 
     /**
-     * @return string
+     * Returns the low field of the clock sequence (bits 73-80 of the UUID).
+     *
+     * @return string Hexadecimal value of clock_seq_low
      */
     public function getClockSeqLowHex();
 
     /**
-     * @return string
+     * Returns the clock sequence value associated with this UUID.
+     *
+     * @return string Hexadecimal value of clock sequence
      */
     public function getClockSequenceHex();
 
     /**
-     * @return \DateTime
+     * Returns a PHP `DateTime` object representing the timestamp associated
+     * with this UUID.
+     *
+     * The timestamp value is only meaningful in a time-based UUID, which
+     * has version type 1. If this UUID is not a time-based UUID then
+     * this method throws `UnsupportedOperationException`.
+     *
+     * @return \DateTime A PHP DateTime representation of the date
+     * @throws UnsupportedOperationException If this UUID is not a version 1 UUID
      */
     public function getDateTime();
 
     /**
-     * @return \Moontoast\Math\BigNumber
+     * Returns the integer value of the UUID, converted to an appropriate number
+     * representation.
+     *
+     * @return mixed Converted representation of the unsigned 128-bit integer value
      */
     public function getInteger();
 
     /**
-     * @return string
+     * Returns the least significant 64 bits of this UUID's 128 bit value.
+     *
+     * @return string Hexadecimal value of least significant bits
      */
     public function getLeastSignificantBitsHex();
 
     /**
-     * @return string
+     * Returns the most significant 64 bits of this UUID's 128 bit value.
+     *
+     * @return string Hexadecimal value of most significant bits
      */
     public function getMostSignificantBitsHex();
 
     /**
-     * @return string
+     * Returns the node value associated with this UUID
+     *
+     * For UUID version 1, the node field consists of an IEEE 802 MAC
+     * address, usually the host address. For systems with multiple IEEE
+     * 802 addresses, any available one can be used. The lowest addressed
+     * octet (octet number 10) contains the global/local bit and the
+     * unicast/multicast bit, and is the first octet of the address
+     * transmitted on an 802.3 LAN.
+     *
+     * For systems with no IEEE address, a randomly or pseudo-randomly
+     * generated value may be used; see RFC 4122, Section 4.5. The
+     * multicast bit must be set in such addresses, in order that they
+     * will never conflict with addresses obtained from network cards.
+     *
+     * For UUID version 3 or 5, the node field is a 48-bit value constructed
+     * from a name as described in RFC 4122, Section 4.3.
+     *
+     * For UUID version 4, the node field is a randomly or pseudo-randomly
+     * generated 48-bit value as described in RFC 4122, Section 4.4.
+     *
+     * @return string Hexadecimal value of node
+     * @link http://tools.ietf.org/html/rfc4122#section-4.1.6
      */
     public function getNodeHex();
 
     /**
-     * @return string
+     * Returns the high field of the timestamp multiplexed with the version
+     * number (bits 49-64 of the UUID).
+     *
+     * @return string Hexadecimal value of time_hi_and_version
      */
     public function getTimeHiAndVersionHex();
 
     /**
-     * @return string
+     * Returns the low field of the timestamp (the first 32 bits of the UUID).
+     *
+     * @return string Hexadecimal value of time_low
      */
     public function getTimeLowHex();
 
     /**
-     * @return string
+     * Returns the middle field of the timestamp (bits 33-48 of the UUID).
+     *
+     * @return string Hexadecimal value of time_mid
      */
     public function getTimeMidHex();
 
     /**
-     * @return string
+     * Returns the timestamp value associated with this UUID.
+     *
+     * The 60 bit timestamp value is constructed from the time_low,
+     * time_mid, and time_hi fields of this UUID. The resulting
+     * timestamp is measured in 100-nanosecond units since midnight,
+     * October 15, 1582 UTC.
+     *
+     * The timestamp value is only meaningful in a time-based UUID, which
+     * has version type 1. If this UUID is not a time-based UUID then
+     * this method throws UnsupportedOperationException.
+     *
+     * @return string Hexadecimal value of the timestamp
+     * @throws UnsupportedOperationException If this UUID is not a version 1 UUID
+     * @link http://tools.ietf.org/html/rfc4122#section-4.1.4
      */
     public function getTimestampHex();
 
     /**
+     * Returns the string representation of the UUID as a URN.
+     *
      * @return string
+     * @link http://en.wikipedia.org/wiki/Uniform_Resource_Name
      */
     public function getUrn();
 
     /**
-     * @return integer
+     * Returns the variant number associated with this UUID.
+     *
+     * The variant number describes the layout of the UUID. The variant
+     * number has the following meaning:
+     *
+     * * 0 - Reserved for NCS backward compatibility
+     * * 2 - The RFC 4122 variant (used by this class)
+     * * 6 - Reserved, Microsoft Corporation backward compatibility
+     * * 7 - Reserved for future definition
+     *
+     * @return int
+     * @link http://tools.ietf.org/html/rfc4122#section-4.1.1
      */
     public function getVariant();
 
     /**
-     * @return integer|null
+     * Returns the version number associated with this UUID.
+     *
+     * The version number describes how this UUID was generated and has the
+     * following meaning:
+     *
+     * * 1 - Time-based UUID
+     * * 2 - DCE security UUID
+     * * 3 - Name-based UUID hashed with MD5
+     * * 4 - Randomly generated UUID
+     * * 5 - Name-based UUID hashed with SHA-1
+     *
+     * Returns null if this UUID is not an RFC 4122 variant, since version
+     * is only meaningful for this variant.
+     *
+     * @return int|null
+     * @link http://tools.ietf.org/html/rfc4122#section-4.1.3
      */
     public function getVersion();
 
     /**
+     * Converts this UUID into a string representation.
+     *
      * @return string
      */
     public function toString();