Update Ecto.UUID.generate/1 docs

Author: ryanwinchester

lib/ecto/uuid.ex

@@ -215,14 +215,54 @@ defmodule Ecto.UUID do
 
   @default_version 4
   @doc """
-  Generates a uuid with the given options.
+  Generates a UUID string.
+
+  ## Options
+
+   * `:version` - The UUID version to generate. Supported values are `4` (random)
+     and `7` (time-ordered). Defaults to `4`.
+
+  ## Options (version 7)
+
+   * `:precision` - The timestamp precision for version 7 UUIDs. Supported values
+     are `:millisecond` and `:nanosecond`. Defaults to `:millisecond`. When using
+     `:nanosecond`, the sub-millisecond precision is encoded in the `rand_a` field.
+     NOTE: Due to the 12-bit space available, nanosecond precision is limited
+     to 4096 (2^12) distinct values per millisecond.
+
+   * `:monotonic` - When `true`, ensures that generated version 7 UUIDs are
+     strictly monotonically increasing, even when multiple UUIDs are generated
+     within the same timestamp. This is useful for maintaining insertion order
+     in databases. Defaults to `false`.
+     NOTE: With `:millisecond` precision, generating multiple UUIDs within the
+     same millisecond increments the timestamp by 1ms for each UUID, causing the
+     embedded timestamp to drift ahead of real time under high throughput.
+     Using `precision: :nanosecond` reduces this drift significantly, as
+     timestamps only advance by ~244ns per UUID when generation outpaces real
+     time.
+
+  ## Examples
+
+      > Ecto.UUID.generate()
+      "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
+
+      > Ecto.UUID.generate(version: 7)
+      "018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a"
+
+      > Ecto.UUID.generate(version: 7, precision: :nanosecond)
+      "018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a"
+
+      > Ecto.UUID.generate(version: 7, monotonic: true)
+      "018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a"
+
   """
   @spec generate() :: t
   @spec generate(options) :: t
   def generate(opts \\ []), do: encode(bingenerate(opts))
 
   @doc """
   Generates a uuid with the given options in binary format.
+  See `generate/1` for options.
   """
   @spec bingenerate(options) :: raw
   def bingenerate(opts \\ []) do