From 6db86389ce89ac777d297e463021e549d6838d93 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Fri, 10 Oct 2025 19:08:38 +0200
Subject: [PATCH 1/2] util/error: Document addTrace params

... and rename e -> pos. That was weird.
---
 src/libutil/include/nix/util/error.hh | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/libutil/include/nix/util/error.hh b/src/libutil/include/nix/util/error.hh
index e564ca5b9..49dd75991 100644
--- a/src/libutil/include/nix/util/error.hh
+++ b/src/libutil/include/nix/util/error.hh
@@ -192,13 +192,23 @@ public:
         err.traces.push_front(trace);
     }
 
+    /**
+     * @param pos Nullable `shared_ptr<Pos>`
+     * @param fs Format string, see `HintFmt`
+     * @param args... Format string arguments.
+     */
     template<typename... Args>
-    void addTrace(std::shared_ptr<const Pos> && e, std::string_view fs, const Args &... args)
+    void addTrace(std::shared_ptr<const Pos> && pos, std::string_view fs, const Args &... args)
     {
-        addTrace(std::move(e), HintFmt(std::string(fs), args...));
+        addTrace(std::move(pos), HintFmt(std::string(fs), args...));
     }
 
-    void addTrace(std::shared_ptr<const Pos> && e, HintFmt hint, TracePrint print = TracePrint::Default);
+    /**
+     * @param pos Nullable `shared_ptr<Pos>`
+     * @param hint Formatted error message
+     * @param print Optional, whether to always print (e.g. `addErrorContext`)
+     */
+    void addTrace(std::shared_ptr<const Pos> && pos, HintFmt hint, TracePrint print = TracePrint::Default);
 
     bool hasTrace() const
     {

From 48a5e2dde2625ebb0d7f6aa2e77051e152fb3411 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 13 Oct 2025 13:14:05 +0200
Subject: [PATCH 2/2] EvalState: add doc comment

---
 src/libexpr/include/nix/expr/eval.hh  |  9 ++++++++-
 src/libutil/include/nix/util/error.hh | 10 +++++++---
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/libexpr/include/nix/expr/eval.hh b/src/libexpr/include/nix/expr/eval.hh
index b87c45ce3..76ce62b87 100644
--- a/src/libexpr/include/nix/expr/eval.hh
+++ b/src/libexpr/include/nix/expr/eval.hh
@@ -508,8 +508,15 @@ private:
 
 public:
 
+    /**
+     * @param lookupPath     Only used during construction.
+     * @param store          The store to use for instantiation
+     * @param fetchSettings  Must outlive the lifetime of this EvalState!
+     * @param settings       Must outlive the lifetime of this EvalState!
+     * @param buildStore     The store to use for builds ("import from derivation", C API `nix_string_realise`)
+     */
     EvalState(
-        const LookupPath & _lookupPath,
+        const LookupPath & lookupPath,
         ref<Store> store,
         const fetchers::Settings & fetchSettings,
         const EvalSettings & settings,
diff --git a/src/libutil/include/nix/util/error.hh b/src/libutil/include/nix/util/error.hh
index 49dd75991..cc8460592 100644
--- a/src/libutil/include/nix/util/error.hh
+++ b/src/libutil/include/nix/util/error.hh
@@ -193,7 +193,9 @@ public:
     }
 
     /**
-     * @param pos Nullable `shared_ptr<Pos>`
+     * Prepends an item to the error trace, as is usual for extra context.
+     *
+     * @param pos Nullable source position to put in trace item
      * @param fs Format string, see `HintFmt`
      * @param args... Format string arguments.
      */
@@ -204,9 +206,11 @@ public:
     }
 
     /**
-     * @param pos Nullable `shared_ptr<Pos>`
+     * Prepends an item to the error trace, as is usual for extra context.
+     *
+     * @param pos Nullable source position to put in trace item
      * @param hint Formatted error message
-     * @param print Optional, whether to always print (e.g. `addErrorContext`)
+     * @param print Optional, whether to always print (used by `addErrorContext`)
      */
     void addTrace(std::shared_ptr<const Pos> && pos, HintFmt hint, TracePrint print = TracePrint::Default);