Add user option to avoid checkdoc warning for unescaped left paren

* lisp/emacs-lisp/checkdoc.el
(checkdoc-column-zero-backslash-before-paren): New user option to
avoid warning on unescaped left parenthesis in column zero.
(checkdoc-this-string-valid-engine): Respect above new option.

diff --git a/etc/NEWS b/etc/NEWS
index 76cfb43efc37fa2a2edf00522a5ee5ffbf4e8465..d4f4c81f8952e40ee08dbe68544d59c037240818 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2825,6 +2825,13 @@ after every monthly meeting which takes place on the third Thursday,
 or if you would like to attend a virtual meeting scheduled in a
 different timezone causing a difference in the date.
 
+---
+*** New user option 'checkdoc-column-zero-backslash-before-paren'.
+Checkdoc warns if there is a left parenthesis in column zero of a
+documentation string.  That warning can now be disabled by customizing
+this new user option to nil.  This can be useful if you don't expect
+your code to be edited with an Emacs version older than 27.1.
+
 ---
 *** The old non-SMIE indentation of 'sh-mode' has been removed.
 

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index bc568f10fceb55456f57766c1d465fd65cc41998..3150ea605f0cb29c3f5d0cfa75471fed1424b4a3 100644 (file)
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -312,6 +312,14 @@ This should be set in an Emacs Lisp file's local variables."
   :version "28.1")
 ;;;###autoload(put 'checkdoc-symbol-words 'safe-local-variable #'checkdoc-list-of-strings-p)
 
+(defcustom checkdoc-column-zero-backslash-before-paren t
+  "Non-nil means to warn if there is no '\\' before '(' in column zero.
+This backslash is no longer needed on Emacs 27.1 later.
+
+See Info node `(elisp) Documentation Tips' for background."
+  :type 'boolean
+  :version "28.1")
+
 ;;;###autoload
 (defun checkdoc-list-of-strings-p (obj)
   "Return t when OBJ is a list of strings."
@@ -1403,16 +1411,17 @@ buffer, otherwise stop after the first error."
              (match-beginning 1)
              (match-end 1)))))
      ;; * Check for '(' in column 0.
-     (save-excursion
-       (when (re-search-forward "^(" e t)
-        (if (checkdoc-autofix-ask-replace (match-beginning 0)
-                                          (match-end 0)
-                                          (format-message "Escape this `('? ")
-                                          "\\(")
-            nil
-          (checkdoc-create-error
-           "Open parenthesis in column 0 should be escaped"
-           (match-beginning 0) (match-end 0)))))
+     (when checkdoc-column-zero-backslash-before-paren
+       (save-excursion
+         (when (re-search-forward "^(" e t)
+           (if (checkdoc-autofix-ask-replace (match-beginning 0)
+                                     (match-end 0)
+                                     (format-message "Escape this `('? ")
+                                     "\\(")
+               nil
+             (checkdoc-create-error
+              "Open parenthesis in column 0 should be escaped"
+              (match-beginning 0) (match-end 0))))))
      ;; * Do not start or end a documentation string with whitespace.
      (let (start end)
        (if (or (if (looking-at "\"\\([ \t\n]+\\)")