Added doc comments to function arguments in func defs that use formals.

src/libexpr/nixexpr.cc

@@ -434,5 +434,12 @@ size_t SymbolTable::totalSize() const
     return n;
 }
 
+Formal::~Formal() {
+  if (this->docComment != 0) {
+    // Free the C string.
+    free(this->docComment);
+    this->docComment = 0;
+  }
+}
 
 }

src/libexpr/nixexpr.hh

@@ -212,7 +212,10 @@ struct Formal
 {
     Symbol name;
     Expr * def;
-    Formal(const Symbol & name, Expr * def) : name(name), def(def) { };
+    char *docComment;
+    Formal(const Symbol & name, Expr * def, char * docComment) : name(name), def(def), docComment(docComment) { };
+
+    ~Formal();
 };
 
 struct Formals

src/libexpr/parser.y

@@ -250,6 +250,7 @@ void yyerror(YYLTYPE * loc, yyscan_t scanner, ParseData * data, const char * err
   const char * id; // !!! -> Symbol
   char * path;
   char * uri;
+  char *doc_comment;
   std::vector<nix::AttrName> * attrNames;
   std::vector<nix::Expr *> * string_parts;
 }
@@ -509,8 +510,12 @@ formals
   ;
 
 formal
-  : ID { $$ = new Formal(data->symbols.create($1), 0); }
-  | ID '?' expr { $$ = new Formal(data->symbols.create($1), $3); }
+  : ID { $$ = new Formal(data->symbols.create($1), 0, 0); }
+  | ID '?' expr { $$ = new Formal(data->symbols.create($1), $3, 0); }
+  | DOC_COMMENT ID { $$ = new Formal(data->symbols.create($2), 0, $1); }
+  | ID DOC_COMMENT { $$ = new Formal(data->symbols.create($1), 0, $2); }
+  | DOC_COMMENT ID '?' expr { $$ = new Formal(data->symbols.create($2), $4, $1); }
+  | ID '?' expr DOC_COMMENT { $$ = new Formal(data->symbols.create($1), $3, $4); }
   ;
 
 %%

src/libexpr/primops.cc

@@ -1196,6 +1196,29 @@ static void prim_functionArgs(EvalState & state, const Pos & pos, Value * * args
     v.attrs->sort();
 }
 
+static void prim_functionArgDocs(EvalState & state, const Pos & pos, Value * * args, Value & v)
+{
+    state.forceValue(*args[0]);
+    if (args[0]->type != tLambda)
+        throw TypeError(format("‘functionArgDocs’ requires a function, at %1%") % pos);
+
+    if (!args[0]->lambda.fun->matchAttrs) {
+        state.mkAttrs(v, 0);
+        return;
+    }
+
+    state.mkAttrs(v, args[0]->lambda.fun->formals->formals.size());
+
+    for (auto & i : args[0]->lambda.fun->formals->formals) {
+        if (i.docComment != NULL)
+          mkString(*state.allocAttr(v, i.name), i.docComment);
+        else
+          mkNull(*state.allocAttr(v,i.name));
+    }
+
+    v.attrs->sort();
+}
+
 
 /*************************************************************
  * Lists
@@ -1835,6 +1858,7 @@ void EvalState::createBaseEnv()
     addPrimOp("__intersectAttrs", 2, prim_intersectAttrs);
     addPrimOp("__catAttrs", 2, prim_catAttrs);
     addPrimOp("__functionArgs", 1, prim_functionArgs);
+    addPrimOp("__functionArgDocs", 1, prim_functionArgDocs);
 
     // Lists
     addPrimOp("__isList", 1, prim_isList);

tests/lang/eval-okay-functionargs-docs.exp

@@ -0,0 +1 @@
+{ a = "aa"; b = "bb"; }

tests/lang/eval-okay-functionargs-docs.nix

@@ -0,0 +1 @@
+builtins.functionArgDocs ({a /*! aa */, /*! bb */ b}: null)