checkdoc: New defvars to disable some warnings

* lisp/emacs-lisp/checkdoc.el (checkdoc--argument-missing-flag)
(checkdoc--disambiguate-symbol-flag)
(checkdoc--interactive-docstring-flag): New defvars to disable some
warnings.  These are intended for use with Emacs itself rather than
with third-party libraries.
(checkdoc-this-string-valid, checkdoc-this-string-valid-engine):
Respect above new variables.

1 files changed, 42 insertions, 10 deletions

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index d7975086878..74186631759 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -331,6 +331,35 @@ See Info node `(elisp) Documentation Tips' for background."
   :type 'boolean
   :version "28.1")
 
+;; This is how you can use checkdoc to make mass fixes on the Emacs
+;; source tree:
+;;
+;; (setq checkdoc--argument-missing-flag nil)      ; optional
+;; (setq checkdoc--disambiguate-symbol-flag nil)   ; optional
+;; (setq checkdoc--interactive-docstring-flag nil) ; optional
+;; Then use `M-x find-dired' ("-name '*.el'") and `M-x checkdoc-dired'
+
+(defvar checkdoc--argument-missing-flag t
+  "Non-nil means warn if arguments are missing from docstring.
+This variable is intended for use on Emacs itself, where the
+large number of libraries means it is impractical to fix all
+of these warnings en masse.  In almost any other case, setting
+this to anything but t is likely to be counter-productive.")
+
+(defvar checkdoc--disambiguate-symbol-flag t
+  "Non-nil means ask to disambiguate Lisp symbol.
+This variable is intended for use on Emacs itself, where the
+large number of libraries means it is impractical to fix all
+of these warnings masse.  In almost any other case, setting
+this to anything but t is likely to be counter-productive.")
+
+(defvar checkdoc--interactive-docstring-flag t
+  "Non-nil means warn if interactive function has no docstring.
+This variable is intended for use on Emacs itself, where the
+large number of libraries means it is impractical to fix all
+of these warnings masse.  In almost any other case, setting
+this to anything but t is likely to be counter-productive.")
+
 ;;;###autoload
 (defun checkdoc-list-of-strings-p (obj)
   "Return t when OBJ is a list of strings."
@@ -1416,12 +1445,13 @@ buffer, otherwise stop after the first error."
                  (checkdoc-create-error
                   "You should convert this comment to documentation"
                   (point) (line-end-position)))
-             (checkdoc-create-error
-              (if (nth 2 fp)
-                  "All interactive functions should have documentation"
-                "All variables and subroutines might as well have a \
+             (when checkdoc--interactive-docstring-flag
+               (checkdoc-create-error
+                (if (nth 2 fp)
+                    "All interactive functions should have documentation"
+                  "All variables and subroutines might as well have a \
 documentation string")
-              (point) (+ (point) 1) t)))))
+                (point) (+ (point) 1) t))))))
     (if (and (not err) (= (following-char) ?\"))
         (with-syntax-table checkdoc-syntax-table
           (checkdoc-this-string-valid-engine fp take-notes))
@@ -1621,6 +1651,7 @@ mouse-[0-3]\\)\\)\\>"))
              (setq mb (match-beginning 1)
                    me (match-end 1))
              (if (and sym (boundp sym) (fboundp sym)
+                      checkdoc--disambiguate-symbol-flag
                       (save-excursion
                         (goto-char mb)
                         (forward-word-strictly -1)
@@ -1798,11 +1829,12 @@ function,command,variable,option or symbol." ms1))))))
                                                   (looking-at "[.?!]")))
                              (insert "."))
                          nil)
-                     (checkdoc-create-error
-                      (format-message
-                       "Argument `%s' should appear (as %s) in the doc string"
-                       (car args) (upcase (car args)))
-                      s (marker-position e)))
+                     (when checkdoc--argument-missing-flag
+                       (checkdoc-create-error
+                        (format-message
+                         "Argument `%s' should appear (as %s) in the doc string"
+                         (car args) (upcase (car args)))
+                        s (marker-position e))))
                  (if (or (and order (eq order 'yes))
                          (and (not order) checkdoc-arguments-in-order-flag))
                      (if (< found last-pos)