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

src/Provider/Node/FallbackNodeProvider.php

@@ -16,15 +16,34 @@ namespace Ramsey\Uuid\Provider\Node;
 
 use Ramsey\Uuid\Provider\NodeProviderInterface;
 
+/**
+ * FallbackNodeProvider attempts to gain the system host ID from an array of
+ * providers, falling back to the next in line in the event a host ID can not be
+ * obtained
+ */
 class FallbackNodeProvider implements NodeProviderInterface
 {
+    /**
+     * @var NodeProviderInterface[]
+     */
     private $nodeProviders;
 
+    /**
+     * Constructs a `FallbackNodeProvider` using an array of node providers
+     *
+     * @param NodeProviderInterface[] $providers Array of node providers
+     */
     public function __construct(array $providers)
     {
         $this->nodeProviders = $providers;
     }
 
+    /**
+     * Returns the system node ID by iterating over an array of node providers
+     * and returning the first non-empty value found
+     *
+     * @return string System node ID as a hexadecimal string
+     */
     public function getNode()
     {
         foreach ($this->nodeProviders as $provider) {

src/Provider/Node/RandomNodeProvider.php

@@ -16,12 +16,21 @@ namespace Ramsey\Uuid\Provider\Node;
 
 use Ramsey\Uuid\Provider\NodeProviderInterface;
 
+/**
+ * RandomNodeProvider provides functionality to generate a random node ID, in
+ * the event that the node ID could not be obtained from the host system
+ *
+ * @link http://tools.ietf.org/html/rfc4122#section-4.5
+ */
 class RandomNodeProvider implements NodeProviderInterface
 {
+    /**
+     * Returns the system node ID
+     *
+     * @return string System node ID as a hexadecimal string
+     */
     public function getNode()
     {
-        // if $node is still null (couldn't get from system), randomly generate
-        // a node value, according to RFC 4122, Section 4.5
         return sprintf('%06x%06x', mt_rand(0, 1 << 24), mt_rand(0, 1 << 24));
     }
 }

src/Provider/Node/SystemNodeProvider.php

@@ -16,8 +16,17 @@ namespace Ramsey\Uuid\Provider\Node;
 
 use Ramsey\Uuid\Provider\NodeProviderInterface;
 
+/**
+ * SystemNodeProvider provides functionality to get the system node ID (MAC
+ * address) using external system calls
+ */
 class SystemNodeProvider implements NodeProviderInterface
 {
+    /**
+     * Returns the system node ID
+     *
+     * @return string System node ID as a hexadecimal string
+     */
     public function getNode()
     {
         static $node = null;
@@ -43,8 +52,6 @@ class SystemNodeProvider implements NodeProviderInterface
     /**
      * Returns the network interface configuration for the system
      *
-     * @todo Needs evaluation and possibly modification to ensure this works
-     *       well across multiple platforms.
      * @codeCoverageIgnore
      * @return string
      */

src/Provider/NodeProviderInterface.php

@@ -14,7 +14,16 @@
 
 namespace Ramsey\Uuid\Provider;
 
+/**
+ * NodeProviderInterface provides functionality to get the node ID (or host ID
+ * in the form of the system's MAC address) from a specific type of node provider
+ */
 interface NodeProviderInterface
 {
+    /**
+     * Returns the system node ID
+     *
+     * @return string System node ID as a hexadecimal string
+     */
     public function getNode();
 }

src/Provider/Time/FixedTimeProvider.php

@@ -16,10 +16,25 @@ namespace Ramsey\Uuid\Provider\Time;
 
 use Ramsey\Uuid\Provider\TimeProviderInterface;
 
+/**
+ * FixedTimeProvider uses an previously-generated timestamp to provide the time
+ *
+ * This provider allows the use of a previously-generated timestamp, such as one
+ * stored in a database, when creating version 1 UUIDs.
+ */
 class FixedTimeProvider implements TimeProviderInterface
 {
+    /**
+     * @var int[] Array containing `sec` and `usec` components of a timestamp
+     */
     private $fixedTime;
 
+    /**
+     * Constructs a `FixedTimeProvider` using the provided `$timestamp`
+     *
+     * @param int[] Array containing `sec` and `usec` components of a timestamp
+     * @throws InvalidArgumentException if the `$timestamp` does not contain `sec` or `usec` components
+     */
     public function __construct(array $timestamp)
     {
         if (!array_key_exists('sec', $timestamp) || !array_key_exists('usec', $timestamp)) {
@@ -29,16 +44,31 @@ class FixedTimeProvider implements TimeProviderInterface
         $this->fixedTime = $timestamp;
     }
 
+    /**
+     * Sets the `usec` component of the timestamp
+     *
+     * @param int $value The `usec` value to set
+     */
     public function setUsec($value)
     {
         $this->fixedTime['usec'] = $value;
     }
 
+    /**
+     * Sets the `sec` component of the timestamp
+     *
+     * @param int $value The `sec` value to set
+     */
     public function setSec($value)
     {
         $this->fixedTime['sec'] = $value;
     }
 
+    /**
+     * Returns a timestamp array
+     *
+     * @return int[] Array containing `sec` and `usec` components of a timestamp
+     */
     public function currentTime()
     {
         return $this->fixedTime;

src/Provider/Time/SystemTimeProvider.php

@@ -16,8 +16,16 @@ namespace Ramsey\Uuid\Provider\Time;
 
 use Ramsey\Uuid\Provider\TimeProviderInterface;
 
+/**
+ * SystemTimeProvider uses built-in PHP functions to provide the time
+ */
 class SystemTimeProvider implements TimeProviderInterface
 {
+    /**
+     * Returns a timestamp array
+     *
+     * @return int[] Array containing `sec` and `usec` components of a timestamp
+     */
     public function currentTime()
     {
         return gettimeofday();

src/Provider/TimeProviderInterface.php

@@ -14,10 +14,16 @@
 
 namespace Ramsey\Uuid\Provider;
 
+/**
+ * TimeProviderInterface provides functionality to get the time from a specific
+ * type of time provider
+ */
 interface TimeProviderInterface
 {
     /**
-     * @return string[] Array guaranteed to contain "sec" and "usec" components of current timestamp.
+     * Returns a timestamp array
+     *
+     * @return int[] Array guaranteed to contain `sec` and `usec` components of a timestamp
      */
     public function currentTime();
 }