Release review fixes: NIF unit format honours :format, README pins, and bang-variant doc sections

Author: kipcole9

CHANGELOG.md

@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Fixed
+
+* `Localize.Unit.to_string/2` with `backend: :nif` honours the `:format` option: the NIF call now receives the requested width, so `format: :short` renders "100 m" on both backends instead of falling back to the long form.
+
 ### Removed
 
 * The deprecated locale-scoped delegates are removed: `Language.available_languages/1` and `known_languages/1` (use `languages_for/1` / `language_names_for/1`), `Script.available_scripts/1` and `known_scripts/1` (use `scripts_for/1` / `script_names_for/1`), `Subdivision.available_subdivisions/1` and `known_subdivisions/1` (use `subdivisions_for/1` / `subdivision_names_for/1`), and `Territory.available_styles/0` (use `known_styles/0`).

README.md

@@ -76,7 +76,7 @@ Add `localize` to your dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:localize, "~> 0.47"}
+    {:localize, "~> 0.50"}
   ]
 end
 ```
@@ -86,7 +86,7 @@ On OTP 26 only:
 ```elixir
 def deps do
   [
-    {:localize, "~> 0.45"},
+    {:localize, "~> 0.50"},
     {:json_polyfill, "~> 0.2 or ~> 1.0"}
   ]
 end

lib/localize.ex

@@ -528,6 +528,10 @@ defmodule Localize do
   > form `Localize.to_string/1` (recommended) or
   > `import Localize, except: [to_string: 1, to_string: 2]`.
 
+  ### Arguments
+
+  * `value` is any term that has a `Localize.Chars` implementation.
+
   ### Returns
 
   * `{:ok, formatted_string}` on success.
@@ -603,6 +607,16 @@ defmodule Localize do
   Same as `to_string/1` but returns the formatted string directly
   or raises on error.
 
+  ### Arguments
+
+  * `value` is any term that has a `Localize.Chars` implementation.
+
+  ### Returns
+
+  * The formatted string.
+
+  * Raises an exception if formatting fails.
+
   ### Examples
 
       iex> Localize.to_string!(1234.5, locale: :de)
@@ -616,11 +630,25 @@ defmodule Localize do
   Same as `to_string/2` but returns the formatted string directly
   or raises on error.
 
+  ### Arguments
+
+  * `value` is any term that has a `Localize.Chars` implementation.
+
+  * `options` is a keyword list of options forwarded to the
+    underlying formatter. Every implementation accepts at least
+    `:locale`.
+
   ### Options
 
   * See `to_string/2` for the supported options. They are forwarded
     unchanged to the type-specific formatter for `value`.
 
+  ### Returns
+
+  * The formatted string.
+
+  * Raises an exception if formatting fails.
+
   ### Examples
 
       iex> Localize.to_string!(~D[2025-07-10], locale: :de, format: :long)

lib/localize/date.ex

@@ -157,10 +157,23 @@ defmodule Localize.Date do
   @doc """
   Same as `to_string/2` but raises on error.
 
+  ### Arguments
+
+  * `date` is a `t:Date.t/0` or any map with one or more of
+    `:year`, `:month`, `:day` keys.
+
+  * `options` is a keyword list of options.
+
   ### Options
 
   See `to_string/2` for the supported options.
 
+  ### Returns
+
+  * A formatted string.
+
+  * Raises an exception if the date cannot be formatted.
+
   ### Examples
 
       iex> Localize.Date.to_string!(~D[2017-07-10], locale: :en)

lib/localize/datetime.ex

@@ -136,10 +136,23 @@ defmodule Localize.DateTime do
   @doc """
   Same as `to_string/2` but raises on error.
 
+  ### Arguments
+
+  * `datetime` is a `t:DateTime.t/0`, `t:NaiveDateTime.t/0`,
+    or any map with date and time keys.
+
+  * `options` is a keyword list of options.
+
   ### Options
 
   See `to_string/2` for the supported options.
 
+  ### Returns
+
+  * A formatted string.
+
+  * Raises an exception if the datetime cannot be formatted.
+
   ### Examples
 
       iex> Localize.DateTime.to_string!(~N[2017-07-10 14:30:00], locale: :en, prefer: :ascii)

lib/localize/language_tag.ex

@@ -229,12 +229,12 @@ defmodule Localize.LanguageTag do
   — this gates atomisation behind a bounded set so untrusted input
   cannot exhaust the atom table.
 
-  ## Arguments
+  ### Arguments
 
   * `locale_id` is any [BCP 47](https://tools.ietf.org/search/bcp47)
     string.
 
-  ## Returns
+  ### Returns
 
   * `{:ok, t:Localize.LanguageTag}` or
 
@@ -287,12 +287,12 @@ defmodule Localize.LanguageTag do
   @doc """
   Parse a locale identifier into a `Localize.LanguageTag` struct and raises on error
 
-  ## Arguments
+  ### Arguments
 
   * `locale_id` is any [BCP 47](https://tools.ietf.org/search/bcp47)
     string.
 
-  ## Returns
+  ### Returns
 
   * `t:Localize.LanguageTag` or
 
@@ -472,6 +472,17 @@ defmodule Localize.LanguageTag do
   Same as `new/1` but returns the struct directly or raises
   an exception.
 
+  ### Arguments
+
+  * `locale_id` is any BCP 47 locale string.
+
+  ### Returns
+
+  * A fully resolved `t:Localize.LanguageTag.t/0` struct.
+
+  * Raises an exception if parsing, canonicalization, or likely
+    subtag resolution fails.
+
   ### Examples
 
       iex> tag = Localize.LanguageTag.new!("zh-TW")
@@ -591,6 +602,17 @@ defmodule Localize.LanguageTag do
   Same as `canonicalize/1` but returns the struct directly
   or raises an exception.
 
+  ### Arguments
+
+  * `language_tag` is a `%Localize.LanguageTag{}` struct.
+
+  ### Returns
+
+  * The canonicalized tag with the `canonical_locale_id` field
+    populated.
+
+  * Raises an exception if extension validation fails.
+
   ### Examples
 
       iex> tag = Localize.LanguageTag.parse!("en-US-u-nu-arab-ca-gregory")
@@ -973,6 +995,17 @@ defmodule Localize.LanguageTag do
   Same as `add_likely_subtags/1` but returns the struct directly
   or raises an exception.
 
+  ### Arguments
+
+  * `language_tag` is a `%Localize.LanguageTag{}` struct.
+
+  ### Returns
+
+  * The maximized tag with all subtags filled in and
+    `canonical_locale_id` updated.
+
+  * Raises an exception if no likely subtags data is found.
+
   ### Examples
 
       iex> tag = Localize.LanguageTag.parse!("en")
@@ -1102,6 +1135,26 @@ defmodule Localize.LanguageTag do
   Same as `remove_likely_subtags/2` but returns the struct directly
   or raises an exception.
 
+  ### Arguments
+
+  * `language_tag` is a `%Localize.LanguageTag{}` struct.
+
+  * `options` is a keyword list of options.
+
+  ### Options
+
+  * `:favor` selects which subtag survives when either the script
+    or the region alone is enough to identify the locale: `:script`
+    (the default) keeps the script, `:region` keeps the region.
+
+  ### Returns
+
+  * The minimized tag with redundant subtags removed and
+    `canonical_locale_id` updated.
+
+  * Raises an exception if maximization fails or `:favor` is
+    invalid.
+
   ### Examples
 
       iex> tag = Localize.LanguageTag.parse!("zh-Hant-TW")

lib/localize/message/interpreter.ex

@@ -1805,9 +1805,9 @@ defmodule Localize.Message.Interpreter do
 
   defp map_unit_options(localize_opts, func_opts) do
     case func_opts[:unitDisplay] do
-      "long" -> Keyword.put(localize_opts, :style, :long)
-      "short" -> Keyword.put(localize_opts, :style, :short)
-      "narrow" -> Keyword.put(localize_opts, :style, :narrow)
+      "long" -> Keyword.put(localize_opts, :format, :long)
+      "short" -> Keyword.put(localize_opts, :format, :short)
+      "narrow" -> Keyword.put(localize_opts, :format, :narrow)
       _other -> localize_opts
     end
   end

lib/localize/message/message.ex

@@ -508,6 +508,13 @@ defmodule Localize.Message do
 
   * See `format_to_safe_list/3` for the supported options.
 
+  ### Returns
+
+  * A list of `safe_node()` tuples.
+
+  * Raises an exception on parse or format error, including
+    unbalanced markup or unbound variables.
+
   ### Examples
 
       iex> Localize.Message.format_to_safe_list!("Hello {$name}!", %{"name" => "World"})

lib/localize/number.ex

@@ -355,6 +355,18 @@ defmodule Localize.Number do
   @doc """
   Same as `to_range_string/2` but raises on error.
 
+  ### Arguments
+
+  * `range` is an Elixir `t:Range.t/0` (e.g., `3..5`).
+
+  * `options` is a keyword list of options. See `to_range_string/3`.
+
+  ### Returns
+
+  * A formatted string.
+
+  * Raises an exception if formatting fails.
+
   ### Examples
 
       iex> Localize.Number.to_range_string!(3..5, locale: :en)

lib/localize/unit.ex

@@ -1915,6 +1915,12 @@ defmodule Localize.Unit do
 
   See `display_name/2` for the supported options.
 
+  ### Returns
+
+  * The localized display name string.
+
+  * Raises an exception if the display name cannot be produced.
+
   ### Examples
 
       iex> Localize.Unit.display_name!("meter", locale: :en)