From d98764ac168ba00b38b9b60b11fb22bb5fb2f98d Mon Sep 17 00:00:00 2001
From: Ben Ramsey <ben@benramsey.com>
Date: Fri, 21 Feb 2020 13:09:00 -0600
Subject: [PATCH] Enhance the Guid documentation

---
 src/Codec/GuidStringCodec.php |  3 ++-
 src/Guid/Fields.php           |  2 ++
 src/Guid/Guid.php             | 15 +++++++++++++++
 src/Guid/GuidBuilder.php      |  2 ++
 4 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/Codec/GuidStringCodec.php b/src/Codec/GuidStringCodec.php
index bbc6d60..221e479 100644
--- a/src/Codec/GuidStringCodec.php
+++ b/src/Codec/GuidStringCodec.php
@@ -14,6 +14,7 @@ declare(strict_types=1);
 
 namespace Ramsey\Uuid\Codec;
 
+use Ramsey\Uuid\Guid\Guid;
 use Ramsey\Uuid\UuidInterface;
 
 use function bin2hex;
@@ -22,7 +23,7 @@ use function substr;
 /**
  * GuidStringCodec encodes and decodes globally unique identifiers (GUID)
  *
- * @link https://en.wikipedia.org/wiki/Globally_unique_identifier Globally Unique Identifier
+ * @see Guid
  */
 class GuidStringCodec extends StringCodec
 {
diff --git a/src/Guid/Fields.php b/src/Guid/Fields.php
index ab2d787..49db4ed 100644
--- a/src/Guid/Fields.php
+++ b/src/Guid/Fields.php
@@ -38,6 +38,8 @@ use const STR_PAD_LEFT;
 /**
  * GUIDs are comprised of a set of named fields, according to RFC 4122
  *
+ * @see Guid
+ *
  * @psalm-immutable
  */
 final class Fields implements FieldsInterface
diff --git a/src/Guid/Guid.php b/src/Guid/Guid.php
index 632b3ff..08a0069 100644
--- a/src/Guid/Guid.php
+++ b/src/Guid/Guid.php
@@ -30,7 +30,22 @@ use Ramsey\Uuid\UuidInterface;
  * > subject to swapping. This byte swapping applies even for versions 3, 4, and
  * > 5, where the canonical fields do not correspond to the content of the UUID.
  *
+ * The first three fields of a GUID are encoded in little-endian byte order,
+ * while the last three fields are in network (big-endian) byte order. This is
+ * according to the history of the Microsoft definition of a GUID.
+ *
+ * According to the .NET Guid.ToByteArray method documentation:
+ *
+ * > Note that the order of bytes in the returned byte array is different from
+ * > the string representation of a Guid value. The order of the beginning
+ * > four-byte group and the next two two-byte groups is reversed, whereas the
+ * > order of the last two-byte group and the closing six-byte group is the
+ * > same.
+ *
  * @link https://en.wikipedia.org/wiki/Universally_unique_identifier#Variants UUID Variants on Wikipedia
+ * @link https://docs.microsoft.com/en-us/windows/win32/api/guiddef/ns-guiddef-guid Windows GUID structure
+ * @link https://docs.microsoft.com/en-us/dotnet/api/system.guid .NET Guid Struct
+ * @link https://docs.microsoft.com/en-us/dotnet/api/system.guid.tobytearray .NET Guid.ToByteArray Method
  *
  * @psalm-immutable
  */
diff --git a/src/Guid/GuidBuilder.php b/src/Guid/GuidBuilder.php
index 5fba49f..b518e4c 100644
--- a/src/Guid/GuidBuilder.php
+++ b/src/Guid/GuidBuilder.php
@@ -25,6 +25,8 @@ use Throwable;
 /**
  * GuidBuilder builds instances of Guid
  *
+ * @see Guid
+ *
  * @psalm-immutable
  */
 class GuidBuilder implements UuidBuilderInterface