New user option checkdoc-arguments-missing-flag

* lisp/emacs-lisp/checkdoc.el
(checkdoc-arguments-missing-flag): New user option.
(checkdoc-this-string-valid-engine): Use above new option.
(checkdoc--argument-missing-flag): Make into obsolete variable alias for
above new option.

2 files changed, 14 insertions, 9 deletions

diff --git a/etc/NEWS b/etc/NEWS
index ef4cacb20f9..da26870f2b1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -931,6 +931,11 @@ This change affects both 'M-x checkdoc' and the corresponding flymake
 backend.
 
 ---
+*** New user option 'checkdoc-arguments-missing-flag'.
+Set this to nil to disable warnings for function arguments that are not
+documented in docstrings.
+
+---
 *** Checkdoc will now flag incorrect formatting in warnings.
 This affects calls to 'warn', 'lwarn', 'display-warning', and
 'message-box'.
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 95fa3a2027e..c3b43b6a97b 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -353,19 +353,19 @@ See Info node `(elisp) Documentation Tips' for background."
 ;; 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-arguments-missing-flag nil)      ; optional
 ;; (setq checkdoc--disambiguate-symbol-flag nil)   ; optional
 ;; (setq checkdoc--interactive-docstring-flag nil) ; optional
 ;; (setq checkdoc-permit-comma-termination-flag t) ; optional
-;; (setq checkdoc-verb-check-experimental-flag nil)
 ;; 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.")
+(define-obsolete-variable-alias 'checkdoc--argument-missing-flag
+  'checkdoc-arguments-missing-flag "31.1")
+(defcustom checkdoc-arguments-missing-flag t
+  "Non-nil means warn if function arguments are missing from docstring."
+  :type 'boolean
+  :version "31.1")
+;;;###autoload(put 'checkdoc-arguments-missing-flag 'safe-local-variable 'booleanp)
 
 (defvar checkdoc--disambiguate-symbol-flag t
   "Non-nil means ask to disambiguate Lisp symbol.
@@ -1852,7 +1852,7 @@ function,command,variable,option or symbol." ms1))))))
                                                   (looking-at "[.?!]")))
                              (insert "."))
                          nil)
-                     (when checkdoc--argument-missing-flag
+                     (when checkdoc-arguments-missing-flag
                        (checkdoc-create-error
                         (format-message
                          "Argument `%s' should appear (as %s) in the doc string"