master 8f0806d 2/3: checkdoc: New defvars to disable some warnings

[Stefan Kangas]

branch: master
commit 8f0806da1afa8ba1ca7a65c344b484ac449a82f4
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    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.
---
 lisp/emacs-lisp/checkdoc.el | 52 ++++++++++++++++++++++++++++++++++++---------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index d797508..7418663 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)