lib.warn: Update docs

- Bring up to date
- Give meaning to the metavariables
- Use italics for metavariables (just like the Nix manual)
- Don't abbreviate
  - No hard feelings, Val.

1 files changed, 29 insertions, 39 deletions

diff --git a/lib/trivial.nix b/lib/trivial.nix
index 4e9ec8cfbab4..96929462a816 100644
--- a/lib/trivial.nix
+++ b/lib/trivial.nix
@@ -661,47 +661,33 @@ in {
   importTOML = path:
     builtins.fromTOML (builtins.readFile path);
 
-  ## Warnings
-
-  # See https://github.com/NixOS/nix/issues/749. Eventually we'd like these
-  # to expand to Nix builtins that carry metadata so that Nix can filter out
-  # the INFO messages without parsing the message string.
-  #
-  # Usage:
-  # {
-  #   foo = lib.warn "foo is deprecated" oldFoo;
-  #   bar = lib.warnIf (bar == "") "Empty bar is deprecated" bar;
-  # }
-  #
-  # TODO: figure out a clever way to integrate location information from
-  # something like __unsafeGetAttrPos.
-
   /**
-    Print a warning before returning the second argument. This function behaves
-    like `builtins.trace`, but requires a string message and formats it as a
-    warning, including the `warning: ` prefix.
 
-    To get a call stack trace and abort evaluation, set the environment variable
-    `NIX_ABORT_ON_WARN=true` and set the Nix options `--option pure-eval false --show-trace`
+    `warn` *`message`* *`value`*
+
+    Print a warning before returning the second argument.
+
+    See [`builtins.warn`](https://nix.dev/manual/nix/latest/language/builtins.html#builtins-warn) (Nix >= 2.23).
+    On older versions, the Nix 2.23 behavior is emulated with [`builtins.trace`](https://nix.dev/manual/nix/latest/language/builtins.html#builtins-warn), including the [`NIX_ABORT_ON_WARN`](https://nix.dev/manual/nix/latest/command-ref/conf-file#conf-abort-on-warn) behavior, but not the `nix.conf` setting or command line option.
 
     # Inputs
 
-    `msg`
+    *`message`* (String)
 
-    : Warning message to print.
+    : Warning message to print before evaluating *`value`*.
 
-    `val`
+    *`value`* (any value)
 
     : Value to return as-is.
 
     # Type
 
     ```
-    string -> a -> a
+    String -> a -> a
     ```
   */
   warn =
-    # Since https://github.com/NixOS/nix/pull/10592
+    # Since Nix 2.23, https://github.com/NixOS/nix/pull/10592
     builtins.warn or (
       let mustAbort = lib.elem (builtins.getEnv "NIX_ABORT_ON_WARN") ["1" "true" "yes"];
       in
@@ -715,53 +701,57 @@ in {
     );
 
   /**
-    Like warn, but only warn when the first argument is `true`.
 
+    `warnIf` *`condition`* *`message`* *`value`*
+
+    Like `warn`, but only warn when the first argument is `true`.
 
     # Inputs
 
-    `cond`
+    *`condition`* (Boolean)
 
-    : 1\. Function argument
+    : `true` to trigger the warning before continuing with *`value`*.
 
-    `msg`
+    *`message`* (String)
 
-    : 2\. Function argument
+    : Warning message to print before evaluating
 
-    `val`
+    *`value`* (any value)
 
     : Value to return as-is.
 
     # Type
 
     ```
-    bool -> string -> a -> a
+    Bool -> String -> a -> a
     ```
   */
   warnIf = cond: msg: if cond then warn msg else x: x;
 
   /**
-    Like warnIf, but negated (warn if the first argument is `false`).
 
+    `warnIfNot` *`condition`* *`message`* *`value`*
+
+    Like `warnIf`, but negated: warn if the first argument is `false`.
 
     # Inputs
 
-    `cond`
+    *`condition`*
 
-    : 1\. Function argument
+    : `false` to trigger the warning before continuing with `val`.
 
-    `msg`
+    *`message`*
 
-    : 2\. Function argument
+    : Warning message to print before evaluating *`value`*.
 
-    `val`
+    *`value`*
 
     : Value to return as-is.
 
     # Type
 
     ```
-    bool -> string -> a -> a
+    Boolean -> String -> a -> a
     ```
   */
   warnIfNot = cond: msg: if cond then x: x else warn msg;