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

src/Generator/CombGenerator.php

@@ -17,22 +17,32 @@ namespace Ramsey\Uuid\Generator;
 use Ramsey\Uuid\Converter\NumberConverterInterface;
 
 /**
- * Generator to be used for COMB sequential UUID's.
- *
- * @author thibaud
+ * CombGenerator provides functionality to generate COMB (combined GUID/timestamp)
+ * sequential UUIDs
  *
+ * @link https://en.wikipedia.org/wiki/Globally_unique_identifier#Sequential_algorithms
  */
 class CombGenerator implements RandomGeneratorInterface
 {
-
+    /**
+     * @var RandomGeneratorInterface
+     */
     private $randomGenerator;
 
+    /**
+     * @var NumberConverterInterface
+     */
     private $converter;
 
+    /**
+     * @var integer
+     */
     private $timestampBytes;
 
     /**
-     * @param RandomGeneratorInterface $generator RNG for the non-time part.
+     * Constructs a `CombGenerator` using a random-number generator and a number converter
+     *
+     * @param RandomGeneratorInterface $generator Random-number generator for the non-time part.
      * @param NumberConverterInterface $numberConverter Instance of number converter.
      */
     public function __construct(RandomGeneratorInterface $generator, NumberConverterInterface $numberConverter)
@@ -43,7 +53,10 @@ class CombGenerator implements RandomGeneratorInterface
     }
 
     /**
-     * (non-PHPdoc) @see \Ramsey\Uuid\RandomGeneratorInterface::generate()
+     * Generates a string of binary data of the specified length
+     *
+     * @param integer $length The number of bytes of random binary data to generate
+     * @return string A binary string
      */
     public function generate($length)
     {
@@ -68,7 +81,8 @@ class CombGenerator implements RandomGeneratorInterface
 
     /**
      * Returns current timestamp as integer, precise to 0.00001 seconds
-     * @return number
+     *
+     * @return integer
      */
     private function timestamp()
     {

src/Generator/DefaultTimeGenerator.php

@@ -19,6 +19,11 @@ use Ramsey\Uuid\Converter\TimeConverterInterface;
 use Ramsey\Uuid\Provider\NodeProviderInterface;
 use Ramsey\Uuid\Provider\TimeProviderInterface;
 
+/**
+ * DefaultTimeGenerator provides functionality to generate strings of binary
+ * data for version 1 UUIDs based on a host ID, sequence number, and the current
+ * time
+ */
 class DefaultTimeGenerator implements TimeGeneratorInterface
 {
     /**
@@ -36,6 +41,14 @@ class DefaultTimeGenerator implements TimeGeneratorInterface
      */
     private $timeProvider;
 
+    /**
+     * Constructs a `DefaultTimeGenerator` using a node provider, time converter,
+     * and time provider
+     *
+     * @param NodeProviderInterface $nodeProvider
+     * @param TimeConverterInterface $timeConverter
+     * @param TimeProviderInterface $timeProvider
+     */
     public function __construct(
         NodeProviderInterface $nodeProvider,
         TimeConverterInterface $timeConverter,
@@ -46,6 +59,20 @@ class DefaultTimeGenerator implements TimeGeneratorInterface
         $this->timeProvider = $timeProvider;
     }
 
+    /**
+     * 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 string A binary string
+     */
     public function generate($node = null, $clockSeq = null)
     {
         $node = $this->getValidNode($node);
@@ -78,6 +105,13 @@ class DefaultTimeGenerator implements TimeGeneratorInterface
         return hex2bin($hex);
     }
 
+    /**
+     * Uses the node provider given when constructing this instance to get
+     * the node ID (usually a MAC address)
+     *
+     * @param string|int $node A node value that may be used to override the node provider
+     * @return string Hexadecimal representation of the node ID
+     */
     protected function getValidNode($node)
     {
         if ($node === null) {

src/Generator/MtRandGenerator.php

@@ -14,8 +14,20 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * MtRandRandomGenerator provides functionality to generate strings of random
+ * binary data using the `mt_rand()` PHP function
+ *
+ * @link http://php.net/mt_rand
+ */
 class MtRandGenerator implements RandomGeneratorInterface
 {
+    /**
+     * Generates a string of random binary data of the specified length
+     *
+     * @param integer $length The number of bytes of random binary data to generate
+     * @return string A binary string
+     */
     public function generate($length)
     {
         $bytes = '';

src/Generator/OpenSslGenerator.php

@@ -14,9 +14,23 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * OpenSslRandomGenerator provides functionality to generate strings of random
+ * binary data using the `openssl_random_pseudo_bytes()` PHP function
+ *
+ * The use of this generator requires PHP to be compiled using the
+ * `--with-openssl` option.
+ *
+ * @link http://php.net/openssl_random_pseudo_bytes
+ */
 class OpenSslGenerator implements RandomGeneratorInterface
 {
-
+    /**
+     * Generates a string of random binary data of the specified length
+     *
+     * @param integer $length The number of bytes of random binary data to generate
+     * @return string A binary string
+     */
     public function generate($length)
     {
         return openssl_random_pseudo_bytes($length);

src/Generator/PeclUuidRandomGenerator.php

@@ -14,8 +14,20 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * PeclUuidRandomGenerator provides functionality to generate strings of random
+ * binary data using the PECL UUID PHP extension
+ *
+ * @link https://pecl.php.net/package/uuid
+ */
 class PeclUuidRandomGenerator implements RandomGeneratorInterface
 {
+    /**
+     * Generates a string of random binary data of the specified length
+     *
+     * @param integer $length The number of bytes of random binary data to generate
+     * @return string A binary string
+     */
     public function generate($length)
     {
         $uuid = uuid_create(UUID_TYPE_RANDOM);

src/Generator/PeclUuidTimeGenerator.php

@@ -14,8 +14,21 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * PeclUuidTimeGenerator provides functionality to generate strings of binary
+ * data for version 1 UUIDs using the PECL UUID PHP extension
+ *
+ * @link https://pecl.php.net/package/uuid
+ */
 class PeclUuidTimeGenerator implements TimeGeneratorInterface
 {
+    /**
+     * Generate a version 1 UUID using the PECL UUID extension
+     *
+     * @param int|string $node Not used in this context
+     * @param int $clockSeq Not used in this context
+     * @return string A binary string
+     */
     public function generate($node = null, $clockSeq = null)
     {
         $uuid = uuid_create(UUID_TYPE_TIME);

src/Generator/RandomBytesGenerator.php

@@ -14,9 +14,20 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * RandomBytesGenerator provides functionality to generate strings of random
+ * binary data using `random_bytes()` function in PHP 7+
+ *
+ * @link http://php.net/random_bytes
+ */
 class RandomBytesGenerator implements RandomGeneratorInterface
 {
-
+    /**
+     * Generates a string of random binary data of the specified length
+     *
+     * @param integer $length The number of bytes of random binary data to generate
+     * @return string A binary string
+     */
     public function generate($length)
     {
         return random_bytes($length);

src/Generator/RandomGeneratorFactory.php

@@ -14,18 +14,21 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * A factory for retrieving a random generator, based on the environment
+ */
 class RandomGeneratorFactory
 {
     /**
-     * For testing, openssl_random_pseudo_bytes() override; if true, treat as
-     * if openssl_random_pseudo_bytes() is not available
+     * For testing, `openssl_random_pseudo_bytes()` override; if `true`, treat as
+     * if `openssl_random_pseudo_bytes()` is not available
      *
      * @var bool
      */
     public static $forceNoOpensslRandomPseudoBytes = false;
 
     /**
-     * For testing, random_bytes() override; if true, treat as if random_bytes()
+     * For testing, `random_bytes()` override; if `true`, treat as if `random_bytes()`
      * is not available.
      *
      * @var bool
@@ -33,7 +36,7 @@ class RandomGeneratorFactory
     public static $forceNoRandomBytes = false;
 
     /**
-     * Returns true if the system has openssl_random_pseudo_bytes()
+     * Returns `true` if the system has `openssl_random_pseudo_bytes()`
      *
      * @return bool
      */
@@ -43,7 +46,7 @@ class RandomGeneratorFactory
     }
 
     /**
-     * Returns true if the system has random_bytes()
+     * Returns `true` if the system has `random_bytes()`
      *
      * @return bool
      */
@@ -52,6 +55,11 @@ class RandomGeneratorFactory
         return (function_exists('random_bytes') && !self::$forceNoRandomBytes);
     }
 
+    /**
+     * Returns a default random generator, based on the current environment
+     *
+     * @return RandomGeneratorInterface
+     */
     public static function getGenerator()
     {
         if (self::hasRandomBytes()) {

src/Generator/RandomGeneratorInterface.php

@@ -14,12 +14,17 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * RandomGeneratorInterface provides functionality to generate strings of random
+ * binary data
+ */
 interface RandomGeneratorInterface
 {
     /**
-     * @param integer $length
+     * Generates a string of random binary data of the specified length
      *
-     * @return string
+     * @param integer $length The number of bytes of random binary data to generate
+     * @return string A binary string
      */
     public function generate($length);
 }

src/Generator/RandomLibAdapter.php

@@ -17,10 +17,27 @@ namespace Ramsey\Uuid\Generator;
 use RandomLib\Generator;
 use RandomLib\Factory;
 
+/**
+ * RandomLibAdapter provides functionality to generate strings of random
+ * binary data using the ircmaxell/random-lib library
+ *
+ * @link https://packagist.org/packages/ircmaxell/random-lib
+ */
 class RandomLibAdapter implements RandomGeneratorInterface
 {
+    /**
+     * @var Generator
+     */
     private $generator;
 
+    /**
+     * Constructs a `RandomLibAdapter` using a `RandomLib\Generator`
+     *
+     * By default, if no `Generator` is passed in, this creates a medium-strength
+     * generator to use when generating random binary data.
+     *
+     * @param Generator $generator An ircmaxell/random-lib `Generator`
+     */
     public function __construct(Generator $generator = null)
     {
         $this->generator = $generator;
@@ -32,6 +49,12 @@ class RandomLibAdapter implements RandomGeneratorInterface
         }
     }
 
+    /**
+     * Generates a string of random binary data of the specified length
+     *
+     * @param integer $length The number of bytes of random binary data to generate
+     * @return string A binary string
+     */
     public function generate($length)
     {
         return $this->generator->generate($length);

src/Generator/TimeGeneratorFactory.php

@@ -18,6 +18,9 @@ use Ramsey\Uuid\Converter\TimeConverterInterface;
 use Ramsey\Uuid\Provider\NodeProviderInterface;
 use Ramsey\Uuid\Provider\TimeProviderInterface;
 
+/**
+ * A factory for retrieving a time generator, based on the environment
+ */
 class TimeGeneratorFactory
 {
     /**
@@ -35,6 +38,14 @@ class TimeGeneratorFactory
      */
     private $timeProvider;
 
+    /**
+     * Constructs a `TimeGeneratorFactory` using a node provider, time converter,
+     * and time provider
+     *
+     * @param NodeProviderInterface $nodeProvider
+     * @param TimeConverterInterface $timeConverter
+     * @param TimeProviderInterface $timeProvider
+     */
     public function __construct(
         NodeProviderInterface $nodeProvider,
         TimeConverterInterface $timeConverter,
@@ -45,6 +56,11 @@ class TimeGeneratorFactory
         $this->timeProvider = $timeProvider;
     }
 
+    /**
+     * Returns a default time generator, based on the current environment
+     *
+     * @return TimeGeneratorInterface
+     */
     public function getGenerator()
     {
         return new DefaultTimeGenerator(

src/Generator/TimeGeneratorInterface.php

@@ -14,21 +14,22 @@
 
 namespace Ramsey\Uuid\Generator;
 
+/**
+ * TimeGeneratorInterface provides functionality to generate strings of binary
+ * data for version 1 UUIDs based on a host ID, sequence number, and the current
+ * time
+ */
 interface TimeGeneratorInterface
 {
     /**
-     * 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.
+     * 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 string A 16-byte binary string representing a UUID
+     * @return string A binary string
      */
     public function generate($node = null, $clockSeq = null);
 }