Silence checkdoc for symbols designating major and minor modes

[Philip Kaludercic <philipk@posteo.net>]

[-- Attachment #1: Type: text/plain, Size: 730 bytes --]


Hi,

an issue I have been having when documenting code is that checkdoc wants
me to disambiguate symbols referring to major or minor modes. That
usually means adding "function", "command" "variable", "option" or
"symbol" but in my experience these usually do not fit. In fact, most of
the time it is obvious what is meant when referring to a major/minor
mode.

        ... Foo when `bar-mode' is active ...

The patch I added below silences the disambiguation request when a
symbol ends in "-mode". Alternatively, one could also add a "minor mode"
and "major mode" to the list of accepted keywords, but I think that
would sound to repetitive:

        ... Foo when minor mode `bar-mode' is active ...

Opinions?

-- 
	Philip K.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Ignore-ambiguous-symbols-that-end-in-mode.patch --]
[-- Type: text/x-diff, Size: 891 bytes --]

From afbfcec6f0da120c99ff1ff3e0355544c768cb8c Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Tue, 27 Jul 2021 23:43:13 +0200
Subject: [PATCH] Ignore ambiguous symbols that end in "-mode"

* checkdoc.el (checkdoc-this-string-valid-engine): Check if bound and
  fbound symbol ends in "-mode"
---
 lisp/emacs-lisp/checkdoc.el | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index 00cc7777e1..9831a5aa06 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -1559,6 +1559,7 @@ checkdoc-this-string-valid-engine
 	     (setq mb (match-beginning 1)
 		   me (match-end 1))
 	     (if (and sym (boundp sym) (fboundp sym)
+                      (not (string-match-p "-mode\\'" (symbol-name sym)))
 		      (save-excursion
 			(goto-char mb)
 			(forward-word-strictly -1)
-- 
2.30.2