[nongnu] elpa/buttercup d8b596c 240/340: Merge branch 'doc-improve'

[ELPA Syncer]

branch: elpa/buttercup
commit d8b596c59907994924ec3890f3d6579ec8a72c93
Merge: b2edd35 818c150
Author: Ola Nilsson <ola.nilsson@gmail.com>
Commit: Ola Nilsson <ola.nilsson@gmail.com>

    Merge branch 'doc-improve'
    
    * doc-improve:
      docs: Clarify the difference between :var and `let'
      Update some docstrings
      test: Add missing apostrophe in spec title
      docs: Clarify the spy lifespan in writing-tests.md
---
 buttercup.el            |  6 ++++--
 docs/writing-tests.md   | 26 +++++++++++++++++++++++---
 tests/test-buttercup.el |  2 +-
 3 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/buttercup.el b/buttercup.el
index fecc932..c3bec14 100644
--- a/buttercup.el
+++ b/buttercup.el
@@ -205,11 +205,13 @@ failed."
           ,@body)))
 
 (defun buttercup--function-as-matcher (fun)
+  "Wrap FUN in code to unpack function-wrapped arguments."
   (cl-assert (functionp fun) t)
   (lambda (&rest args)
     (apply fun (mapcar #'funcall args))))
 
 (defun buttercup--find-matcher-function (matcher)
+  "Return the matcher function for MATCHER."
   (let ((matcher-prop
          (when (symbolp matcher)
            (get matcher 'buttercup-matcher))))
@@ -1211,7 +1213,7 @@ responsibility to ensure ARG is a command."
            buttercup--spy-contexts))
 
 (defun buttercup--spy-calls-add (spy-function context)
-  "Add CONTEXT to the recorded calls to SPY."
+  "Add CONTEXT to the recorded calls to SPY-FUNCTION."
   (puthash spy-function
            (append (gethash spy-function
                             buttercup--spy-contexts)
@@ -1720,7 +1722,7 @@ FMT and ARGS are passed to `format'."
 
 
 (defadvice display-warning (around buttercup-defer-warnings activate)
-  "Log all warnings to a special buffer while running buttercup tests.
+  "Log all warnings to a special buffer while running buttercup specs.
 
 Emacs' normal display logic for warnings doesn't mix well with
 buttercup, for several reasons. So instead, while a buttercup
diff --git a/docs/writing-tests.md b/docs/writing-tests.md
index 9d6cc54..8ff86e0 100644
--- a/docs/writing-tests.md
+++ b/docs/writing-tests.md
@@ -226,6 +226,10 @@ It's important to note that `lexical-binding` must be 
`non-nil` for
 `:var` and `:var*` to work properly. Within a test file this is
 usually set using a local file variable.
 
+Using `:var` and `:var*` works just like the `let` equivalents, but
+it's recommended to use the `:var` format to be future proof. Future
+internal changes in `buttercup` could break suites using `let`.
+
 ### Setup and Teardown
 
 To help a test suite DRY up any duplicated setup and teardown code,
@@ -361,9 +365,11 @@ pending in results.
 Buttercup has test double functions called spies. While other
 frameworks call these mocks and similar, we call them spies, because
 their main job is to spy in on function calls. Also, Jasmine calls
-them spies, and so do we. A spy can stub any function and tracks calls
+them spies, and so do we. A spy can stub any function - whether it
+already exists or not - and tracks calls
 to it and all arguments. A spy only exists in the `describe` or `it`
-block it is defined in, and will be removed after each spec. There are
+block it is defined in, and will be activated before and deactivated
+and reset after each spec. There are
 special matchers for interacting with spies. The
 `:to-have-been-called` matcher will return true if the spy was called
 at all. The `:to-have-been-called-with` matcher will return true if
@@ -383,7 +389,21 @@ the argument list matches any of the recorded calls to the 
spy.
    (foo 456 "another param"))
 
   (it "tracks that the spy was called"
-    (expect 'foo :to-have-been-called))
+    (expect 'foo :to-have-been-called)
+    (foo 789))
+
+  (it "resets tracking after each spec"
+    (expect 'foo :not :to-have-been-called-with 789))
+
+  (describe "that is defined in a nested `describe'"
+    (before-each
+      (spy-on 'foo :and-return-value 1))
+    (it "will override any outer spy"
+      (expect (foo 789) :to-equal 1)
+      (expect 'foo :not :to-have-been-called-with 123)))
+
+  (it "will not be active outside it's scope"
+    (expect (foo 789) :to-equal nil))
 
   (it "tracks all arguments of its calls"
     (expect 'foo :to-have-been-called-with 123)
diff --git a/tests/test-buttercup.el b/tests/test-buttercup.el
index 6368202..03aa6bb 100644
--- a/tests/test-buttercup.el
+++ b/tests/test-buttercup.el
@@ -1091,7 +1091,7 @@
         (expect 'reporter :to-have-been-called-with 'buttercup-started 
buttercup-suites)
         (expect 'reporter :to-have-been-called-with 'buttercup-done 
buttercup-suites)))
     )
-  (it "should call `buttercup--run-suite once per suite"
+  (it "should call `buttercup--run-suite' once per suite"
     (let ((buttercup-suites (list parent-suite)) runner)
       (ignore runner)
       (setf (symbol-function 'runner) (lambda (suite) (ignore suite)))