docs(3p/nix/libexpr): Add some comments about function calls r/825

These were things that took me a moment to realise.

2 files changed, 10 insertions, 5 deletions

diff --git a/third_party/nix/src/libexpr/eval.cc b/third_party/nix/src/libexpr/eval.cc
index fc1824db8e..4cfcc043be 100644
--- a/third_party/nix/src/libexpr/eval.cc
+++ b/third_party/nix/src/libexpr/eval.cc
@@ -1029,17 +1029,21 @@ void EvalState::callFunction(Value& fun, Value& arg, Value& v, const Pos& pos) {
     return;
   }
 
+  // If the value to be called is an attribute set, check whether it
+  // contains an appropriate function in the '__functor' element and
+  // use that.
   if (fun.type == tAttrs) {
     auto found = fun.attrs->find(sFunctor);
     if (found != fun.attrs->end()) {
-      /* fun may be allocated on the stack of the calling function,
-       * but for functors we may keep a reference, so heap-allocate
-       * a copy and use that instead.
-       */
+      // fun may be allocated on the stack of the calling function,
+      // but for functors we may keep a reference, so heap-allocate a
+      // copy and use that instead
       auto& fun2 = *allocValue();
       fun2 = fun;
       /* !!! Should we use the attr pos here? */
       Value v2;
+      // functors are called with the element itself as the first
+      // parameter, which is partially applied here
       callFunction(*found->second.value, fun2, v2, pos);
       return callFunction(v2, arg, v, pos);
     }
diff --git a/third_party/nix/src/libexpr/nixexpr.hh b/third_party/nix/src/libexpr/nixexpr.hh
index 715dbd8d59..6d5d4f5f55 100644
--- a/third_party/nix/src/libexpr/nixexpr.hh
+++ b/third_party/nix/src/libexpr/nixexpr.hh
@@ -200,10 +200,11 @@ struct ExprList : Expr {
 
 struct Formal {
   Symbol name;
-  Expr* def;
+  Expr* def; // def = default, not definition
   Formal(const Symbol& name, Expr* def) : name(name), def(def){};
 };
 
+// Describes structured function arguments (e.g. `{ a }: ...`)
 struct Formals {
   typedef std::list<Formal> Formals_;
   Formals_ formals;