Fix ert-font-lock macro signatures

* doc/misc/ert.texi (Syntax Highlighting Tests):
* test/lisp/emacs-lisp/ert-font-lock-tests.el
(test-line-comment-p--emacs-lisp, test-line-comment-p--shell-script)
(test-line-comment-p--javascript, test-line-comment-p--python)
(test-line-comment-p--c, test-macro-test--correct-highlighting)
(test-macro-test--docstring, test-macro-test--failing)
(test-macro-test--file, test-macro-test--file-no-asserts)
(test-macro-test--file-failing): Reindent macro calls.
(with-temp-buffer-str-mode): Evaluate macro arguments left-to-right.
(ert-font-lock--wrap-begin-end): Use rx for more robust composition.
(test-line-comment-p--php): Require that php-mode is callable, not
already loaded.

* lisp/emacs-lisp/ert-font-lock.el (ert-font-lock-deftest)
(ert-font-lock-deftest-file): NAME is not followed by an empty list
like in ert-deftest, so the optional DOCSTRING is actually the
second argument.  Adapt calling convention in docstring, and debug,
doc-string, and indent properties accordingly (bug#76372).  Fix
docstring grammar, document MAJOR-MODE, and avoid referring to a
file name as a path.

doc/misc/ert.texi

@@ -955,7 +955,7 @@ checking face assignment.  Test assertions are included in code-level
 comments directly and can be read either from inline strings or files.
 The parser expects the input string to contain at least one assertion.
 
-Test assertion parser extracts tests from comment-only lines.  Every
+The test assertion parser extracts tests from comment-only lines.  Every
 comment assertion line starts either with a caret (@samp{^}) or an arrow
 (@samp{<-}).  A single caret/arrow or carets should be followed
 immediately by the name of a face or a list of faces to be checked
@@ -977,7 +977,7 @@ var variable = 11;
 @end example
 
 Both symbol-only @code{:face} property values and assertion face values
-are normalized to single element lists so assertions below are
+are normalized to single element lists so the assertions below are
 equivalent:
 
 @example
@@ -1068,13 +1068,13 @@ file:
 
 @lisp
 (ert-font-lock-deftest-file test-macro-test--file
-    "Test reading correct assertions from a file"
+  "Test reading correct assertions from a file."
   javascript-mode
   "correct.js")
 @end lisp
 
 The @code{ert-font-lock-deftest} and @code{ert-font-lock-deftest-file}
-macros accept the same keyword parameters as @code{ert-deftest} i.e.,
+macros accept the same keyword arguments as @code{ert-deftest}, i.e.,
 @code{:tag} and @code{:expected-result}.
 
 @node How to Debug Tests

lisp/emacs-lisp/ert-font-lock.el

@@ -27,8 +27,8 @@
 ;; highlighting provided by font-lock.
 ;;
 ;; ert-font-lock entry points are functions
-;; `ert-font-lock-test-string' and `ert-font-lock-test-file' and
+;; `ert-font-lock-test-string' and `ert-font-lock-test-file', and
-;; convenience macros: `ert-font-lock-deftest' and
+;; convenience macros `ert-font-lock-deftest' and
 ;; `ert-font-lock-deftest-file'.
 ;;
 ;; See unit tests in ert-font-lock-tests.el for usage examples.
@@ -124,19 +124,21 @@ Argument TEST-NAME - name of the currently running ert test."
 (defmacro ert-font-lock-deftest (name &rest docstring-keys-mode-and-str)
   "Define test NAME (a symbol) using assertions from TEST-STR.
 
-Other than MAJOR-MODE and TEST-STR parameters, this macro accepts
+The MAJOR-MODE symbol determines the syntax and font lock of TEST-STR.
-the same parameters and keywords as `ert-deftest' and is intended
-to be used through `ert'.
 
-\(fn NAME () [DOCSTRING] [:expected-result RESULT-TYPE] \
+Except for the MAJOR-MODE and TEST-STR parameters, this macro accepts
+the same arguments and keywords as `ert-deftest' and is intended to be
+used through `ert'.
+
+\(fn NAME [DOCSTRING] [:expected-result RESULT-TYPE] \
 [:tags \\='(TAG...)] MAJOR-MODE TEST-STR)"
   (declare (debug (&define [&name "test@" symbolp]
-                           sexp [&optional stringp]
+                           [&optional stringp]
                            [&rest keywordp sexp]
                            symbolp
                            stringp))
-           (doc-string 3)
+           (doc-string 2)
-           (indent 2))
+           (indent 1))
   (pcase-let ((`(,documentation
                  ,documentation-supplied-p
                  ,keys ,mode ,arg)
@@ -159,22 +161,23 @@ to be used through `ert'.
 (defmacro ert-font-lock-deftest-file (name &rest docstring-keys-mode-and-file)
   "Define test NAME (a symbol) using assertions from FILE.
 
-FILE - path to a file with assertions in ERT resource director as
+FILE names a file with assertions in the ERT resource directory, as
-return by `ert-resource-directory'.
+returned by `ert-resource-directory'.  The MAJOR-MODE symbol determines
+the syntax and font lock of FILE's contents.
 
-Other than MAJOR-MODE and FILE parameters, this macro accepts the
+Except for the MAJOR-MODE and FILE parameters, this macro accepts the
-same parameters and keywords as `ert-deftest' and is intended to
+same arguments and keywords as `ert-deftest' and is intended to be used
-be used through `ert'.
+through `ert'.
 
-\(fn NAME () [DOCSTRING] [:expected-result RESULT-TYPE] \
+\(fn NAME [DOCSTRING] [:expected-result RESULT-TYPE] \
 [:tags \\='(TAG...)] MAJOR-MODE FILE)"
   (declare (debug (&define [&name "test@" symbolp]
-                           sexp [&optional stringp]
+                           [&optional stringp]
                            [&rest keywordp sexp]
                            symbolp
                            stringp))
-           (doc-string 3)
+           (doc-string 2)
-           (indent 2))
+           (indent 1))
 
   (pcase-let ((`(,documentation
                  ,documentation-supplied-p

test/lisp/emacs-lisp/ert-font-lock-tests.el

@@ -39,13 +39,13 @@
   "Create a buffer with STR contents and MODE. "
   (declare (indent 1) (debug t))
   `(with-temp-buffer
-     (insert ,str)
      (,mode)
+     (insert ,str)
      (goto-char (point-min))
      ,@body))
 
 (defun ert-font-lock--wrap-begin-end (re)
-  (concat "^" re "$"))
+  (rx bol (regexp re) eol))
 
 ;;; Regexp tests
 ;;;
@@ -117,7 +117,7 @@
 
 (declare-function php-mode "php-mode")
 (ert-deftest test-line-comment-p--php ()
-  (skip-unless (featurep 'php-mode))
+  (skip-unless (fboundp 'php-mode))
 
   (with-temp-buffer-str-mode php-mode
     "echo 'Not a comment'
@@ -591,18 +591,18 @@ var abc = function(d) {
 ;; ^ wrong-face")
 
 (ert-font-lock-deftest-file test-macro-test--file
-    "Test reading correct assertions from a file"
+  "Test reading correct assertions from a file."
   javascript-mode
   "correct.js")
 
 (ert-font-lock-deftest-file test-macro-test--file-no-asserts
-    "Check failing on files without assertions"
+  "Check failing on files without assertions."
   :expected-result :failed
   javascript-mode
   "no-asserts.js")
 
 (ert-font-lock-deftest-file test-macro-test--file-failing
-    "Test reading wrong assertions from a file"
+  "Test reading wrong assertions from a file."
   :expected-result :failed
   javascript-mode
   "broken.js")