tests/function/repl: Characterise the missing doc comment behavior

src/libexpr/nixexpr.cc

@@ -584,6 +584,8 @@ std::string ExprLambda::showNamePos(const EvalState & state) const
 }
 
 void ExprLambda::setDocComment(DocComment docComment) {
+    // RFC 145 specifies that the innermost doc comment wins.
+    // See https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md#ambiguous-placement
     if (!this->docComment) {
         this->docComment = docComment;
 

tests/functional/repl/doc-comment-curried-args.expected

@@ -0,0 +1,24 @@
+Nix <nix version>
+Type :? for help.
+Added <number omitted> variables.
+
+Function curriedArgs
+    … defined at
+    /path/to/tests/functional/repl/doc-comments.nix:48:5
+
+    A documented function.
+
+
+"Note that users may not expect this to behave as it currently does"
+
+Function curriedArgs
+    … defined at
+    /path/to/tests/functional/repl/doc-comments.nix:50:5
+
+    The function returned by applying once
+
+"This won't produce documentation, because we can't actually document arbitrary values"
+
+error: value does not have documentation
+
+

tests/functional/repl/doc-comment-curried-args.in

@@ -0,0 +1,7 @@
+:l doc-comments.nix
+:doc curriedArgs
+x = curriedArgs 1        
+"Note that users may not expect this to behave as it currently does"
+:doc x
+"This won't produce documentation, because we can't actually document arbitrary values"
+:doc x 2

tests/functional/repl/doc-comment-formals.expected

@@ -0,0 +1,13 @@
+Nix <nix version>
+Type :? for help.
+Added <number omitted> variables.
+
+"Note that this is not yet complete"
+
+Function documentedFormals
+    … defined at
+    /path/to/tests/functional/repl/doc-comments.nix:57:5
+
+    Finds x
+
+

tests/functional/repl/doc-comment-formals.in

@@ -0,0 +1,3 @@
+:l doc-comments.nix
+"Note that this is not yet complete"
+:doc documentedFormals

tests/functional/repl/doc-comments.nix

@@ -17,6 +17,7 @@
 
   compact=/**boom*/x: x;
 
+  # https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md#ambiguous-placement
   /** Ignore!!! */
   unambiguous = 
     /** Very close */
@@ -41,17 +42,19 @@
 
   # TODO
 
-  # /** This returns a documented function. */
+  /** You won't see this. */
-  # documentedArgs =
+  curriedArgs =
-  #   /** x */
+    /** A documented function. */
-  #   x:
+    x:
-  #   /** y */
+    /** The function returned by applying once */
-  #   y:
+    y:
-  #   /** x + y */
+    /** A function body performing summation of two items */
-  #   x + y;
+    x + y;
 
-  # /** Documented formals */
+  /** Documented formals (but you won't see this comment) */
-  # documentedFormals = 
+  documentedFormals =
-  #   /** x */
+    /** Finds x */
-  #   x: x;
+    { /** The x attribute */
+      x
+    }: x;
 }

tests/functional/repl/doc-constant.expected

@@ -7,24 +7,24 @@ error: value does not have documentation
 Attribute version
 
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:29:3
+    /path/to/tests/functional/repl/doc-comments.nix:30:3
 
     Immovably fixed.
 
 Attribute empty
 
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:32:3
+    /path/to/tests/functional/repl/doc-comments.nix:33:3
 
     Unchangeably constant.
 
 error:
        … while evaluating the attribute 'attr.undocument'
-         at /path/to/tests/functional/repl/doc-comments.nix:32:3:
+         at /path/to/tests/functional/repl/doc-comments.nix:33:3:
-           31|   /** Unchangeably constant. */
+           32|   /** Unchangeably constant. */
-           32|   lib.attr.empty = { };
+           33|   lib.attr.empty = { };
              |   ^
-           33|
+           34|
 
        error: attribute 'undocument' missing
        at «string»:1:1:
@@ -35,28 +35,28 @@ error:
 Attribute constant
 
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:26:3
+    /path/to/tests/functional/repl/doc-comments.nix:27:3
 
     Firmly rigid.
 
 Attribute version
 
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:29:3
+    /path/to/tests/functional/repl/doc-comments.nix:30:3
 
     Immovably fixed.
 
 Attribute empty
 
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:32:3
+    /path/to/tests/functional/repl/doc-comments.nix:33:3
 
     Unchangeably constant.
 
 Attribute undocumented
 
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:34:3
+    /path/to/tests/functional/repl/doc-comments.nix:35:3
 
     No documentation found.
 
@@ -87,11 +87,11 @@ error: attribute 'missing' missing
 
 error:
        … while evaluating the attribute 'attr.undocumental'
-         at /path/to/tests/functional/repl/doc-comments.nix:32:3:
+         at /path/to/tests/functional/repl/doc-comments.nix:33:3:
-           31|   /** Unchangeably constant. */
+           32|   /** Unchangeably constant. */
-           32|   lib.attr.empty = { };
+           33|   lib.attr.empty = { };
              |   ^
-           33|
+           34|
 
        error: attribute 'undocumental' missing
        at «string»:1:1:

tests/functional/repl/doc-lambda-flavors.expected

@@ -4,25 +4,25 @@ Added <number omitted> variables.
 
 Function nonStrict
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:36:70
+    /path/to/tests/functional/repl/doc-comments.nix:37:70
 
     My syntax is not strict, but I'm strict anyway.
 
 Function strict
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:37:63
+    /path/to/tests/functional/repl/doc-comments.nix:38:63
 
     I don't have to be strict, but I am anyway.
 
 Function strictPre
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:39:48
+    /path/to/tests/functional/repl/doc-comments.nix:40:48
 
     Here's one way to do this
 
 Function strictPost
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:40:53
+    /path/to/tests/functional/repl/doc-comments.nix:41:53
 
     Here's another way to do this
 

tests/functional/repl/doc-unambiguous.expected

@@ -4,7 +4,7 @@ Added <number omitted> variables.
 
 Function unambiguous
     … defined at
-    /path/to/tests/functional/repl/doc-comments.nix:23:5
+    /path/to/tests/functional/repl/doc-comments.nix:24:5
 
     Very close