Improve builtins.path docs wrt recursive, sha256

src/libexpr/primops.cc

@@ -3002,16 +3002,19 @@ static RegisterPrimOp primop_path({
 
         - recursive\
           When `false`, when `path` is added to the store it is with a
-          flat hash, rather than a hash of the NAR serialization of the
-          file. Thus, `path` must refer to a regular file, not a
+          [flat hash](@docroot@/store/file-system-object/content-address.md#serial-flat),
+          rather than a hash of the
+          [NAR serialization](@docroot@/store/file-system-object/content-address.md#serial-nix-archive)
+          of the file. Thus, `path` must refer to a regular file, not a
           directory. This allows similar behavior to `fetchurl`. Defaults
           to `true`.
 
         - sha256\
-          When provided, this is the expected hash of the file at the
-          path. Evaluation fails if the hash is incorrect, and
-          providing a hash allows `builtins.path` to be used even when the
-          `pure-eval` nix config option is on.
+          When provided, this is the expected
+          [content hash](@docroot@/store/file-system-object/content-address.md)
+          of the path. Evaluation fails if the hash is incorrect,
+          and providing a hash allows `builtins.path` to be used even
+          when the `pure-eval` nix config option is on.
     )",
     .fun = prim_path,
 });

tests/functional/lang/eval-okay-path.exp

@@ -1 +1 @@
-[ "/nix/store/ya937r4ydw0l6kayq8jkyqaips9c75jm-output" "/nix/store/m7y372g6jb0g4hh1dzmj847rd356fhnz-output" ]
+[ "/nix/store/ya937r4ydw0l6kayq8jkyqaips9c75jm-output" "/nix/store/m7y372g6jb0g4hh1dzmj847rd356fhnz-output" "/nix/store/a517xfygy9w2q5i3c2dbm50sw4p70b4c-output" ]

tests/functional/lang/eval-okay-path.nix

@@ -1,15 +1,23 @@
 [
+  # NAR hash of directory with filter
   (builtins.path {
     path = ./.;
     filter = path: _: baseNameOf path == "data";
     recursive = true;
     sha256 = "1yhm3gwvg5a41yylymgblsclk95fs6jy72w0wv925mmidlhcq4sw";
     name = "output";
   })
+  # Flat hash of file
   (builtins.path {
     path = ./data;
     recursive = false;
     sha256 = "0k4lwj58f2w5yh92ilrwy9917pycipbrdrr13vbb3yd02j09vfxm";
     name = "output";
   })
+  # NAR hash of directory (recursive = true is the default)
+  (builtins.path {
+    path = ./dir1;
+    sha256 = "02vlkcjkl1rvy081n6d40qi73biv2w4b9x9biklay4ncgk77zr1f";
+    name = "output";
+  })
 ]