From f46e0b0644fa503742e76eaf3e8a3b97281d7fd8 Mon Sep 17 00:00:00 2001
From: Ben Ramsey <ben@benramsey.com>
Date: Sun, 8 Mar 2020 15:59:10 -0500
Subject: [PATCH] [ci skip] Complete documentation for nonstandard UUIDs

---
 docs/nonstandard/other.rst            | 44 +++++++++++++++++++++++++++
 docs/reference.rst                    |  2 ++
 docs/reference/nonstandard-fields.rst | 13 ++++++++
 docs/reference/nonstandard-uuid.rst   | 20 ++++++++++++
 4 files changed, 79 insertions(+)
 create mode 100644 docs/reference/nonstandard-fields.rst
 create mode 100644 docs/reference/nonstandard-uuid.rst

diff --git a/docs/nonstandard/other.rst b/docs/nonstandard/other.rst
index ac86400..f7e5a41 100644
--- a/docs/nonstandard/other.rst
+++ b/docs/nonstandard/other.rst
@@ -3,3 +3,47 @@
 =======================
 Other Nonstandard UUIDs
 =======================
+
+Sometimes, you might encounter a string that looks like a UUID but doesn't
+follow the `RFC 4122`_ specification. Take this string, for example:
+
+.. code-block:: text
+
+    d95959bc-2ff5-43eb-fccd-14883ba8f174
+
+At a glance, this looks like a valid UUID, but the variant bits don't match RFC
+4122. Instead of throwing a validation exception, ramsey/uuid will assume this
+is a UUID, since it fits the format and has 128 bits, but it will represent it
+as a :php:class:`Ramsey\\Uuid\\Nonstandard\\Uuid`.
+
+.. code-block:: php
+    :caption: Create an instance of Nonstandard\\Uuid from a non-RFC 4122 UUID
+
+    use Ramsey\Uuid\Uuid;
+
+    $uuid = Uuid::fromString('d95959bc-2ff5-43eb-fccd-14883ba8f174');
+
+    printf(
+        "Class: %s\nUUID: %s\nVersion: %d\nVariant: %s\n",
+        get_class($uuid),
+        $uuid->toString(),
+        $uuid->getFields()->getVersion(),
+        $uuid->getFields()->getVariant()
+    );
+
+This will create a Nonstandard\\Uuid from the given string and print out a few
+details about it. It will look something like this:
+
+.. code-block:: text
+
+    Class: Ramsey\Uuid\Nonstandard\Uuid
+    UUID: d95959bc-2ff5-43eb-fccd-14883ba8f174
+    Version: 0
+    Variant: 7
+
+Note that the version is 0. Since the variant is 7, and there is no
+formal specification for this variant of UUID, ramsey/uuid has no way of knowing
+what type of UUID this is.
+
+
+.. _RFC 4122: https://tools.ietf.org/html/rfc4122
diff --git a/docs/reference.rst b/docs/reference.rst
index 1f8e587..19bade5 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -20,6 +20,8 @@ Reference
     reference/nonstandard-uuidv6
     reference/guid-fields
     reference/guid-guid
+    reference/nonstandard-fields
+    reference/nonstandard-uuid
     reference/types
     reference/exceptions
     reference/helper
diff --git a/docs/reference/nonstandard-fields.rst b/docs/reference/nonstandard-fields.rst
new file mode 100644
index 0000000..b4196c9
--- /dev/null
+++ b/docs/reference/nonstandard-fields.rst
@@ -0,0 +1,13 @@
+.. _reference.nonstandard.fields:
+
+===================
+Nonstandard\\Fields
+===================
+
+.. php:namespace:: Ramsey\Uuid\Nonstandard
+
+.. php:class:: Fields
+
+    Implements :php:interface:`Ramsey\\Uuid\\Rfc4122\\FieldsInterface`.
+
+    Nonstandard\Fields represents the fields of a nonstandard UUID.
diff --git a/docs/reference/nonstandard-uuid.rst b/docs/reference/nonstandard-uuid.rst
new file mode 100644
index 0000000..152169f
--- /dev/null
+++ b/docs/reference/nonstandard-uuid.rst
@@ -0,0 +1,20 @@
+.. _reference.nonstandard.uuid:
+
+=================
+Nonstandard\\Uuid
+=================
+
+.. php:namespace:: Ramsey\Uuid\Nonstandard
+
+.. php:class:: Uuid
+
+    Implements :php:interface:`Ramsey\\Uuid\\UuidInterface`.
+
+    Nonstandard\Uuid represents :ref:`nonstandard.other`. In addition to
+    providing the methods defined on the interface, this class additionally
+    provides the following methods.
+
+    .. php:method:: getFields()
+
+        :returns: The fields that comprise this UUID
+        :returntype: Ramsey\\Uuid\\Nonstandard\\Fields