From 6247f78b3dd10afd2ed172b01e64ce6a48b573cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christina=20S=C3=B8rensen?= <christina@cafkafk.com>
Date: Wed, 11 Sep 2024 16:24:21 +0200
Subject: [PATCH] docs(primops): document functions in `primops.cc`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

WIP

Change-Id: I99eb29f3bdc4f1f6aefb5add61b3167e939cd09f
Signed-off-by: Christina Sørensen <christina@cafkafk.com>
---
 src/libexpr/primops.cc | 107 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/src/libexpr/primops.cc b/src/libexpr/primops.cc
index dab96d6d4..734f8efb6 100644
--- a/src/libexpr/primops.cc
+++ b/src/libexpr/primops.cc
@@ -254,6 +254,21 @@ static void import(EvalState & state, const PosIdx pos, Value & vPath, Value * v
 static RegisterPrimOp primop_scopedImport(PrimOp {
     .name = "scopedImport",
     .arity = 2,
+    .args = {"scope", "path"},
+    .doc = R"(
+      Imports a *path* with a given attrset *scope* injected.
+
+      This is conceptually equivalent to `import path`, where the
+      contents of path get's wrapped in a `with scope`.
+
+      > **Note**
+      >
+      > Scoped import has some *nasty* performance implications, since it
+      > disables the parse/eval cache.
+
+      `scopedImport` is generally considered an operation to avoid, unless
+      there are exceptional reasons to justify its usage.
+    )",
     .fun = [](EvalState & state, const PosIdx pos, Value * * args, Value & v)
     {
         import(state, pos, *args[1], args[0], v);
@@ -814,6 +829,33 @@ static void prim_addErrorContext(EvalState & state, const PosIdx pos, Value * *
 static RegisterPrimOp primop_addErrorContext(PrimOp {
     .name = "__addErrorContext",
     .arity = 2,
+    .args = {"s", "expr"},
+    .doc = R"(
+      Adds additional error message *s* to the trace of *expr* on failure.
+
+      This is useful for giving addition information on failure. For example,
+
+      ```nix
+      builtins.addErrorContext "This error is intentional" (assert false; 10)
+      ```
+
+      will throw a stack trace like this:
+
+      ```
+      error:
+        … while calling the 'addErrorContext' builtin
+          at «string»:1:1:
+             1| builtins.addErrorContext "This error is intentional" (assert false; 10)
+              | ^
+
+        … This error is intentional
+
+        error: assertion 'false' failed
+        at «string»:1:55:
+             1| builtins.addErrorContext "This error is intentional" (assert false; 10)
+              |
+      ```
+    )",
     .fun = prim_addErrorContext,
 });
 
@@ -1423,6 +1465,44 @@ drvName, Bindings * attrs, Value & v)
 static RegisterPrimOp primop_derivationStrict(PrimOp {
     .name = "derivationStrict",
     .arity = 1,
+    .args = {"derivation"},
+    .doc = R"(
+      derivationStrict takes an attrSet *derivation* and turns it into
+      a *set* representing a derivation.
+
+      `derivationStrict` construct (as a unobservable side effect) a Nix
+      derivation expression that performs the derivation described by the
+      argument set.
+
+      Returns the original set extended with the following attributes:
+      `outPath' containing the primary output path of the derivation; `drvPath'
+      containing the path of the Nix expression; and `type' set to `derivation'
+      to indicate that this is a derivation.
+
+      For instance,
+
+      ```nix
+      builtins.derivationStrict {
+        name = "foo";
+        builder = "/bin/sh";
+        args = [ ];
+        system = "x86_64-linux";
+        outputs = ["foo"];
+      }
+      ```
+
+      evaluates to
+
+      ```nix
+      {
+        drvPath = "/nix/store/rm2qi6fdyryhrzm1l3r0y70zgg811fmf-foo.drv";
+        foo = "/nix/store/x22z6v41yzkj4qs2m8j1wkcy4gjznmw2-foo-foo";
+      }
+      ```
+
+      builtins.derivation is technically an internal wrapper around
+      builtins.derivationStrict.
+    )",
     .fun = prim_derivationStrict,
 });
 
@@ -2511,6 +2591,33 @@ static void prim_unsafeGetAttrPos(EvalState & state, const PosIdx pos, Value * *
 static RegisterPrimOp primop_unsafeGetAttrPos(PrimOp {
     .name = "__unsafeGetAttrPos",
     .arity = 2,
+    .args = {"s", "set"}
+    .doc = R"(
+      Searches *set* for the location of attribute *s*, where *s* is a string.
+
+      The output is an attrSet consisting of column, line, and file where a
+      match is found. For instance, to find the location of `stdenvNoCC` in
+      nixpkgs:
+
+      ```nix
+      builtins.unsafeGetAttrPos "stdenvNoCC" pkgs
+      ````
+
+      which will output,
+
+      ```nix
+      {
+        column = 20;
+        file = "/nix/store/w7wryrbg7r3sl31fcd74yw2kva42nlw9-source/pkgs/top-level/stage.nix";
+        line = 148;
+      }
+      ```
+
+      > **Note**
+      >
+      > The position given isn't always excact, hence it should not be relied
+      > on beyond manually finding things.
+    )",
     .fun = prim_unsafeGetAttrPos,
 });