[ci skip] Complete documentation for nonstandard UUIDs

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

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

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.

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