From 74698d54c82fa302dc0c82f68c796eda673090d9 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Wed, 10 Jul 2024 13:34:42 +0200
Subject: [PATCH] Document builtins.derivation

---
 src/libexpr/primops/derivation.nix            | 29 +++++++++++++++++--
 .../lang/eval-fail-derivation-name.err.exp    | 24 +++++++--------
 2 files changed, 39 insertions(+), 14 deletions(-)

diff --git a/src/libexpr/primops/derivation.nix b/src/libexpr/primops/derivation.nix
index c0fbe8082..f329ff71e 100644
--- a/src/libexpr/primops/derivation.nix
+++ b/src/libexpr/primops/derivation.nix
@@ -1,6 +1,31 @@
-/* This is the implementation of the ‘derivation’ builtin function.
-   It's actually a wrapper around the ‘derivationStrict’ primop. */
+# This is the implementation of the ‘derivation’ builtin function.
+# It's actually a wrapper around the ‘derivationStrict’ primop.
+# Note that the following comment will be shown in :doc in the repl, but not in the manual.
 
+/**
+  Create a derivation.
+
+  # Inputs
+
+  The single argument is an attribute set that describes what to build and how to build it.
+  See https://nix.dev/manual/nix/2.23/language/derivations
+
+  # Output
+
+  The result is an attribute set that describes the derivation.
+  Notably it contains the outputs, which in the context of the Nix language are special strings that refer to the output paths, which may not yet exist.
+  The realisation of these outputs only occurs when needed; for example
+
+    * When `nix-build` or a similar command is run, it realises the outputs that were requested on its command line.
+      See https://nix.dev/manual/nix/2.23/command-ref/nix-build
+
+    * When `import`, `readFile`, `readDir` or some other functions are called, they have to realise the outputs they depend on.
+      This is referred to as "import from derivation".
+      See https://nix.dev/manual/nix/2.23/language/import-from-derivation
+
+  Note that `derivation` is very bare-bones, and provides almost no commands during the build.
+  Most likely, you'll want to use functions like `stdenv.mkDerivation` in Nixpkgs to set up a basic environment.
+*/
 drvAttrs @ { outputs ? [ "out" ], ... }:
 
 let
diff --git a/tests/functional/lang/eval-fail-derivation-name.err.exp b/tests/functional/lang/eval-fail-derivation-name.err.exp
index eb2206df1..ae7b47712 100644
--- a/tests/functional/lang/eval-fail-derivation-name.err.exp
+++ b/tests/functional/lang/eval-fail-derivation-name.err.exp
@@ -1,24 +1,24 @@
 error:
        … while evaluating the attribute 'outPath'
-         at <nix/derivation-internal.nix>:19:9:
-           18|       value = commonAttrs // {
-           19|         outPath = builtins.getAttr outputName strict;
+         at <nix/derivation-internal.nix>:44:9:
+           43|       value = commonAttrs // {
+           44|         outPath = builtins.getAttr outputName strict;
              |         ^
-           20|         drvPath = strict.drvPath;
+           45|         drvPath = strict.drvPath;
 
        … while calling the 'getAttr' builtin
-         at <nix/derivation-internal.nix>:19:19:
-           18|       value = commonAttrs // {
-           19|         outPath = builtins.getAttr outputName strict;
+         at <nix/derivation-internal.nix>:44:19:
+           43|       value = commonAttrs // {
+           44|         outPath = builtins.getAttr outputName strict;
              |                   ^
-           20|         drvPath = strict.drvPath;
+           45|         drvPath = strict.drvPath;
 
        … while calling the 'derivationStrict' builtin
-         at <nix/derivation-internal.nix>:9:12:
-            8|
-            9|   strict = derivationStrict drvAttrs;
+         at <nix/derivation-internal.nix>:34:12:
+           33|
+           34|   strict = derivationStrict drvAttrs;
              |            ^
-           10|
+           35|
 
        … while evaluating derivation '~jiggle~'
          whose name attribute is located at /pwd/lang/eval-fail-derivation-name.nix:2:3