Obsolete Flymake's flymake-diagnostic-types-alist

That varaiable was an association between symbols and properties,
effecively duplicating symbol's property lists.  It is simpler to just
put properties on symbols.  Backward compatibility to the old variable
has been kept.

* doc/misc/flymake.texi (Flymake error types): Don't mention
flymake-diagnostic-types-alist.
(Flymake error types): Rework section.
(Backend functions): Refill a paragraph.
(Flymake utility functions): Don't mention
flymake-diagnostic-types-alist.
(Proc customization variables): Don't mention
flymake-diagnostic-types-alist.

* etc/NEWS: Mention obsoletion of flymake-diagnostic-types-alist.

* lisp/progmodes/flymake-proc.el
(flymake-proc--diagnostics-for-pattern): Don't use
flymake-diagnostic-types-alist.

* lisp/progmodes/flymake.el: Rewrite commentary.
(flymake-make-diagnostic, flymake-mode, flymake-goto-next-error)
(flymake-goto-prev-error): Don't mention
flymake-diagnostic-types-alist in docstring.
(flymake-diagnostic-types-alist): Make obsolete.
(:error, :warning, :note): Put flymake-category in these symbols.
(flymake-error, flymake-warning, flymake-note): Put
`flymake-bitmap', not `bitmap' in these symbols.
(flymake--lookup-type-property, flymake--highlight-line): Rewrite.
Honor flymake-diagnostic-types-alist for backward
compatibility.

* lisp/progmodes/python.el (python-flymake-msg-alist): Don't
mention flymake-diagnostic-types-alist.

5 files changed, 228 insertions, 172 deletions

diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi
index 9260f4f22ba..e7f4da75bb9 100644
--- a/doc/misc/flymake.texi
+++ b/doc/misc/flymake.texi
@@ -275,54 +275,61 @@ The following sections discuss each approach in detail.
 @cindex customizing error types
 @cindex error types, customization
 
-@vindex flymake-diagnostic-types-alist
-The variable @code{flymake-diagnostic-types-alist} is looked up by
-Flymake every time an annotation for a diagnostic is created in the
-buffer.  Specifically, this variable holds a table of correspondence
-between symbols designating diagnostic types and an additional
-sub-table of properties pertaining to each diagnostic type.
-
-Both tables are laid out in association list (@pxref{Association
-Lists,,, elisp, The Emacs Lisp Reference Manual}) format, and thus can
-be conveniently accessed with the functions of the @code{assoc}
-family.
-
-You can use any symbol-value association in the properties sub-table,
-but some symbols have special meaning as to where and how Flymake
-presents the diagnostic:
+To customize the appearance of error types, set properties on the
+symbols associated with each diagnostic type.  The standard diagnostic
+symbols are @code{:error}, @code{:warning} and @code{:note} (though
+the backend may define more, @pxref{Backend functions}).
+
+The following properties can be set:
 
 @itemize
 
 @item
 @cindex bitmap of diagnostic
-@code{bitmap}, an image displayed in the fringe according to
+@code{flymake-bitmap}, an image displayed in the fringe according to
 @code{flymake-fringe-indicator-position}.  The value actually follows
 the syntax of @code{flymake-error-bitmap} (@pxref{Customizable
 variables}).  It is overridden by any @code{before-string} overlay
 property.
 
 @item
-@cindex severity of diagnostic
-@code{severity} is a non-negative integer specifying the diagnostic's
-severity.  The higher the value, the more serious is the error.  If
-the overlay property @code{priority} is not specified, @code{severity}
-is used to set it and help sort overlapping overlays.
+@code{flymake-overlay-control}, an alist ((@var{OVPROP} . @var{VALUE})
+@var{...}) of further properties used to affect the appearance of
+Flymake annotations.  With the exception of @code{category} and
+@code{evaporate}, these properties are applied directly to the created
+overlay (@pxref{Overlay Properties,,, elisp, The Emacs Lisp Reference
+Manual}).
 
-@item
-Every property pertaining to overlays (@pxref{Overlay Properties,,,
-elisp, The Emacs Lisp Reference Manual}), except @code{category} and
-@code{evaporate}.  These properties are used to affect the appearance
-of Flymake annotations.
+As an example, here's how to make diagnostics of the type @code{:note}
+stand out more prominently:
 
-As an example, here's how to make errors (diagnostics of the type
-@code{:error}) stand out even more prominently in the buffer, by
-raising the characters using a @code{display} overlay property.
+@example
+(push '(face . highlight) (get :note 'flymake-overlay-control))
+@end example
+
+If you push another alist entry in front, it overrides the previous
+one.  So this effectively removes the face from @code{:note}
+diagnostics:
 
 @example
-(push '(display . (raise 1.2))
-      (cdr (assoc :error flymake-diagnostic-types-alist)))
+(push '(face . nil) (get :note 'flymake-overlay-control))
 @end example
 
+To restore the original look for @code{:note} types, empty or remove
+its @code{flymake-overlay-control} property:
+
+@example
+(put :note 'flymake-overlay-control '())
+@end example
+
+@item
+@cindex severity of diagnostic
+@code{flymake-severity} is a non-negative integer specifying the
+diagnostic's severity.  The higher the value, the more serious is the
+error.  If the overlay property @code{priority} is not specified in
+@code{flymake-overlay-control}, @code{flymake-severity} is used to set
+it and help sort overlapping overlays.
+
 @item
 @vindex flymake-category
 @code{flymake-category} is a symbol whose property list is considered
@@ -333,32 +340,29 @@ the default for missing values of any other properties.
 @vindex flymake-error
 @vindex flymake-warning
 @vindex flymake-note
-Three default diagnostic types, @code{:error}, @code{:warning} and
-@code{:note} are predefined in
-@code{flymake-diagnostic-types-alist}.  By default each lists a single
+Three default diagnostic types are predefined: @code{:error},
+@code{:warning}, and @code{:note}.  By default, each one of them has a
 @code{flymake-category} property whose value is, respectively, the
-symbols @code{flymake-error}, @code{flymake-warning} and
+category symbol @code{flymake-error}, @code{flymake-warning} and
 @code{flymake-note}.
 
-These category symbols' plists is where the values of customizable
-variables and faces such as @code{flymake-error-bitmap} are found.
-Thus, if you change their plists, Flymake may stop honoring these
-user customizations.
+These category symbols' plist is where the values of customizable
+variables and faces (such as @code{flymake-error-bitmap}) are found.
+Thus, if you change their plists, Flymake may stop honoring these user
+customizations.
 
-The @code{flymake-category} special property is also especially useful
-for backends which create diagnostics objects with non-default
-types that differ from an existing type by only a few properties
-(@pxref{Flymake utility functions}).
+The @code{flymake-category} special property is especially useful for
+backends which create diagnostics objects with non-default types that
+differ from an existing type by only a few properties (@pxref{Flymake
+utility functions}).
 
 As an example, consider configuring a new diagnostic type
-@code{:low-priority-note} that behaves much like the @code{:note}
-priority but without an overlay face.
+@code{:low-priority-note} that behaves much like @code{:note}, but
+without an overlay face.
 
 @example
-(add-to-list
- 'flymake-diagnostic-types-alist
- `(:low-priority-note . ((face . nil)
-                         (flymake-category . flymake-note))))
+(put :low-priority-note 'flymake-overlay-control '((face . nil)))
+(put :low-priority-note 'flymake-category 'flymake-note)
 @end example
 
 @vindex flymake-diagnostics
@@ -389,20 +393,17 @@ Internet search for the text of a @code{:warning} or @code{:error}.
     (eww-browse-url
        (concat
         "https://duckduckgo.com/?q="
-        (replace-regexp-in-string " "
-                                  "+"
-                                  (flymake-diagnostic-text topmost-diag)))
+        (replace-regexp-in-string
+          " " "+" (flymake-diagnostic-text topmost-diag)))
        t)))
 
 (dolist (type '(:warning :error))
-  (let ((a (assoc type flymake-diagnostic-types-alist)))
-    (setf (cdr a)
-          (append `((mouse-face . highlight)
-                    (keymap . ,(let ((map (make-sparse-keymap)))
-                                 (define-key map [mouse-2]
-                                   'my-search-for-message)
-                                 map)))
-                  (cdr a)))))
+  (push '(mouse-face . highlight) (get type 'flymake-overlay-control))
+  (push `(keymap . ,(let ((map (make-sparse-keymap)))
+                      (define-key map [mouse-2]
+                        'my-search-for-message)
+                      map))
+        (get type 'flymake-overlay-control)))
 @end example
 
 @node Backend functions
@@ -436,10 +437,10 @@ the first argument is always @var{report-fn}, a callback function
 detailed below;
 
 @item
-the remaining arguments are keyword-value pairs of the
-form @w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}.  Currently,
-Flymake provides no such arguments, but backend functions must be
-prepared to accept (and possibly ignore) any number of them.
+the remaining arguments are keyword-value pairs of the form
+@w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}.
+Currently, Flymake provides no such arguments, but backend functions
+must be prepared to accept (and possibly ignore) any number of them.
 @end itemize
 
 Whenever Flymake or the user decide to re-check the buffer, backend
@@ -512,9 +513,9 @@ by calling the function @code{flymake-make-diagnostic}.
 
 @deffn Function flymake-make-diagnostic buffer beg end type text
 Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to
-@var{end}.  @var{type} is a key to
-@code{flymake-diagnostic-types-alist} and @var{text} is a description
-of the problem detected in this region.
+@var{end}.  @var{type} is a diagnostic symbol (@pxref{Flymake error
+types}), and @var{text} is a description of the problem detected in
+this region.
 @end deffn
 
 @cindex access diagnostic object
@@ -715,14 +716,13 @@ Patterns for error/warning messages in the form @code{(regexp file-idx
 line-idx col-idx err-text-idx)}.  @xref{Parsing the output}.
 
 @item flymake-proc-diagnostic-type-pred
-A function to classify a diagnostic text as particular type of
-error.  Should be a function taking an error text and returning one of
-the symbols indexing @code{flymake-diagnostic-types-alist}.  If non-nil
-is returned but there is no such symbol in that table, a warning is
-assumed.  If nil is returned, an error is assumed.  Can also be a
-regular expression that should match only warnings.  This variable
-replaces the old @code{flymake-warning-re} and
-@code{flymake-warning-predicate}.
+A function to classify a diagnostic text as particular type of error.
+Should be a function taking an error text and returning a diagnostic
+symbol (@pxref{Flymake error types}).  If non-nil is returned but
+there is no such symbol in that table, a warning is assumed.  If nil
+is returned, an error is assumed.  Can also be a regular expression
+that should match only warnings.  This variable replaces the old
+@code{flymake-warning-re} and @code{flymake-warning-predicate}.
 
 @item flymake-proc-compilation-prevents-syntax-check
 A flag indicating whether compilation and syntax check of the same
diff --git a/etc/NEWS b/etc/NEWS
index 1b324986d94..01dcb441a7d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -176,6 +176,13 @@ interface that's more like functions like @code{search-forward}.
 It now treats the optional 2nd argument to mean that the URL should be
 shown in the currently selected window.
 
+** Flymake
+
++++
+*** The variable 'flymake-diagnostic-types-alist' is obsolete
+You should instead set properties on known diagnostic symbols, like
+':error' and ':warning', as demonstrated in the Flymake manual.
+
 ** Package
 *** New 'package-quickstart' feature
 When 'package-quickstart' is non-nil, package.el precomputes a big autoloads
diff --git a/lisp/progmodes/flymake-proc.el b/lisp/progmodes/flymake-proc.el
index e38e4a75d45..8600be9b97c 100644
--- a/lisp/progmodes/flymake-proc.el
+++ b/lisp/progmodes/flymake-proc.el
@@ -196,11 +196,10 @@ from compile.el")
   'flymake-proc-default-guess
   "Predicate matching against diagnostic text to detect its type.
 Takes a single argument, the diagnostic's text and should return
-a value suitable for indexing
-`flymake-diagnostic-types-alist' (which see).  If the returned
-value is nil, a type of `:error' is assumed.  For some backward
-compatibility, if a non-nil value is returned that doesn't
-index that alist, a type of `:warning' is assumed.
+a diagnostic symbol naming a type.  If the returned value is nil,
+a type of `:error' is assumed.  For some backward compatibility,
+if a non-nil value is returned that doesn't name a type,
+`:warning' is assumed.
 
 Instead of a function, it can also be a string, a regular
 expression.  A match indicates `:warning' type, otherwise
@@ -516,8 +515,8 @@ Create parent directories as needed."
                       :error))
                    ((functionp pred)
                     (let ((probe (funcall pred message)))
-                      (cond ((assoc-default probe
-                                            flymake-diagnostic-types-alist)
+                      (cond ((and (symbolp probe)
+                                  (get probe 'flymake-category))
                              probe)
                             (probe
                              :warning)
diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index ec933ad16ba..27bf1bd17a9 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -34,13 +34,77 @@
 ;; results produced by these backends, as well as entry points for
 ;; backends to hook on to.
 ;;
-;; The main entry points are `flymake-mode' and `flymake-start'
+;; The main interactive entry point is the `flymake-mode' minor mode,
+;; which periodically and automatically initiates checks as the user
+;; is editing the buffer.  The variables `flymake-no-changes-timeout',
+;; `flymake-start-syntax-check-on-newline' and
+;; `flymake-start-on-flymake-mode' give finer control over the events
+;; triggering a check, as does the interactive command
+;; `flymake-start', which immediately starts a check.
 ;;
-;; The docstrings of these variables are relevant to understanding how
-;; Flymake works for both the user and the backend programmer:
+;; Shortly after each check, a summary of collected diagnostics should
+;; appear in the mode-line.  If it doesn't, there might not be a
+;; suitable Flymake backend for the current buffer's major mode, in
+;; which case Flymake will indicate this in the mode-line.  The
+;; indicator will be `!' (exclamation mark), if all the configured
+;; backends errored (or decided to disable themselves) and `?'
+;; (question mark) if no backends were even configured.
 ;;
-;; * `flymake-diagnostic-functions'
-;; * `flymake-diagnostic-types-alist'
+;; For programmers interested in writing a new Flymake backend, the
+;; docstring of `flymake-diagnostic-functions', the Flymake manual,
+;; and the code of existing backends are probably a good starting
+;; point.
+;;
+;; The user wishing to customize the appearance of error types should
+;; set properties on the symbols associated with each diagnostic type.
+;; The standard diagnostic symbols are `:error', `:warning' and
+;; `:note' (though a specific backend may define and use more).  The
+;; following properties can be set:
+;;
+;; * `flymake-bitmap', an image displayed in the fringe according to
+;; `flymake-fringe-indicator-position'.  The value actually follows
+;; the syntax of `flymake-error-bitmap' (which see).  It is overridden
+;; by any `before-string' overlay property.
+;;
+;; * `flymake-severity', a non-negative integer specifying the
+;; diagnostic's severity.  The higher, the more serious.  If the
+;; overlay property `priority' is not specified, `severity' is used to
+;; set it and help sort overlapping overlays.
+;;
+;; * `flymake-overlay-control', an alist ((OVPROP . VALUE) ...) of
+;; further properties used to affect the appearance of Flymake
+;; annotations.  With the exception of `category' and `evaporate',
+;; these properties are applied directly to the created overlay.  See
+;; Info Node `(elisp)Overlay Properties'.
+;;
+;; * `flymake-category', a symbol whose property list is considered a
+;; default for missing values of any other properties.  This is useful
+;; to backend authors when creating new diagnostic types that differ
+;; from an existing type by only a few properties.  The category
+;; symbols `flymake-error', `flymake-warning' and `flymake-note' make
+;; good candidates for values of this property.
+;;
+;; For instance, to omit the fringe bitmap displayed for the standard
+;; `:note' type, set its `flymake-bitmap' property to nil:
+;;
+;;   (put :note 'flymake-bitmap nil)
+;;
+;; To change the face for `:note' type, add a `face' entry to its
+;; `flymake-overlay-control' property.
+;;
+;;   (push '(face . highlight) (get :note 'flymake-overlay-control))
+;;
+;; If you push another alist entry in front, it overrides the previous
+;; one.  So this effectively removes the face from `:note'
+;; diagnostics.
+;;
+;;   (push '(face . nil) (get :note 'flymake-overlay-control))
+;;
+;; To erase customizations and go back to the original look for
+;; `:note' types:
+;;
+;;   (cl-remf (symbol-plist :note) 'flymake-overlay-control)
+;;   (cl-remf (symbol-plist :note) 'flymake-bitmap)
 ;;
 ;;; Code:
 
@@ -232,10 +296,9 @@ generated it."
                                 text
                                 &optional data)
   "Make a Flymake diagnostic for BUFFER's region from BEG to END.
-TYPE is a key to `flymake-diagnostic-types-alist' and TEXT is a
-description of the problem detected in this region.  DATA is any
-object that the caller wishes to attach to the created diagnostic
-for later retrieval."
+TYPE is a key to symbol and TEXT is a description of the problem
+detected in this region.  DATA is any object that the caller
+wishes to attach to the created diagnostic for later retrieval."
   (flymake--diag-make :buffer buffer :beg beg :end end
                       :type type :text text :data data))
 
@@ -426,74 +489,56 @@ Currently accepted REPORT-KEY arguments are:
 
 (put 'flymake-diagnostic-functions 'safe-local-variable #'null)
 
-(defvar flymake-diagnostic-types-alist
-  `((:error
-     . ((flymake-category . flymake-error)))
-    (:warning
-     . ((flymake-category . flymake-warning)))
-    (:note
-     . ((flymake-category . flymake-note))))
-  "Alist ((KEY . PROPS)*) of properties of Flymake diagnostic types.
-KEY designates a kind of diagnostic can be anything passed as
-`:type' to `flymake-make-diagnostic'.
-
-PROPS is an alist of properties that are applied, in order, to
-the diagnostics of the type designated by KEY.  The recognized
-properties are:
-
-* Every property pertaining to overlays, except `category' and
-  `evaporate' (see Info Node `(elisp)Overlay Properties'), used
-  to affect the appearance of Flymake annotations.
-
-* `bitmap', an image displayed in the fringe according to
-  `flymake-fringe-indicator-position'.  The value actually
-  follows the syntax of `flymake-error-bitmap' (which see).  It
-  is overridden by any `before-string' overlay property.
-
-* `severity', a non-negative integer specifying the diagnostic's
-  severity.  The higher, the more serious.  If the overlay
-  property `priority' is not specified, `severity' is used to set
-  it and help sort overlapping overlays.
-
-* `flymake-category', a symbol whose property list is considered
-  a default for missing values of any other properties.  This is
-  useful to backend authors when creating new diagnostic types
-  that differ from an existing type by only a few properties.")
+(put :error 'flymake-category 'flymake-error)
+(put :warning 'flymake-category 'flymake-warning)
+(put :note 'flymake-category 'flymake-note)
+
+(defvar flymake-diagnostic-types-alist `() "")
+(make-obsolete-variable
+ 'flymake-diagnostic-types-alist
+ "Set properties on the diagnostic symbols instead. See Info
+Node `(Flymake)Flymake error types'"
+ "27.1")
 
 (put 'flymake-error 'face 'flymake-error)
-(put 'flymake-error 'bitmap 'flymake-error-bitmap)
+(put 'flymake-error 'flymake-bitmap 'flymake-error-bitmap)
 (put 'flymake-error 'severity (warning-numeric-level :error))
 (put 'flymake-error 'mode-line-face 'compilation-error)
 
 (put 'flymake-warning 'face 'flymake-warning)
-(put 'flymake-warning 'bitmap 'flymake-warning-bitmap)
+(put 'flymake-warning 'flymake-bitmap 'flymake-warning-bitmap)
 (put 'flymake-warning 'severity (warning-numeric-level :warning))
 (put 'flymake-warning 'mode-line-face 'compilation-warning)
 
 (put 'flymake-note 'face 'flymake-note)
-(put 'flymake-note 'bitmap 'flymake-note-bitmap)
+(put 'flymake-note 'flymake-bitmap 'flymake-note-bitmap)
 (put 'flymake-note 'severity (warning-numeric-level :debug))
 (put 'flymake-note 'mode-line-face 'compilation-info)
 
 (defun flymake--lookup-type-property (type prop &optional default)
-  "Look up PROP for TYPE in `flymake-diagnostic-types-alist'.
-If TYPE doesn't declare PROP in either
-`flymake-diagnostic-types-alist' or in the symbol of its
+  "Look up PROP for diagnostic TYPE.
+If TYPE doesn't declare PROP in its plist or in the symbol of its
 associated `flymake-category' return DEFAULT."
-  (let ((alist-probe (assoc type flymake-diagnostic-types-alist)))
-    (cond (alist-probe
-           (let* ((alist (cdr alist-probe))
-                  (prop-probe (assoc prop alist)))
-             (if prop-probe
-                 (cdr prop-probe)
-               (if-let* ((cat (assoc-default 'flymake-category alist))
-                         (plist (and (symbolp cat)
-                                     (symbol-plist cat)))
-                         (cat-probe (plist-member plist prop)))
-                   (cadr cat-probe)
-                 default))))
-          (t
-           default))))
+  ;; This function also consults `flymake-diagnostic-types-alist' for
+  ;; backward compatibility.
+  ;;
+  (if (plist-member (symbol-plist type) prop)
+      ;; allow nil values to survive
+      (get type prop)
+    (let (alist)
+      (or
+       (alist-get
+        prop (setq
+              alist
+              (alist-get type flymake-diagnostic-types-alist)))
+       (when-let* ((cat (or
+                         (get type 'flymake-category)
+                         (alist-get 'flymake-category alist)))
+                   (plist (and (symbolp cat)
+                               (symbol-plist cat)))
+                   (cat-probe (plist-member plist prop)))
+         (cadr cat-probe))
+       default))))
 
 (defun flymake--fringe-overlay-spec (bitmap &optional recursed)
   (if (and (symbolp bitmap)
@@ -510,34 +555,38 @@ associated `flymake-category' return DEFAULT."
                              (list bitmap)))))))
 
 (defun flymake--highlight-line (diagnostic)
-  "Highlight buffer with info in DIAGNOSTIC."
-  (when-let* ((ov (make-overlay
+  "Highlight buffer with info in DIGNOSTIC."
+  (when-let* ((type (flymake--diag-type diagnostic))
+              (ov (make-overlay
                    (flymake--diag-beg diagnostic)
                    (flymake--diag-end diagnostic))))
-    ;; First set `category' in the overlay, then copy over every other
-    ;; property.
+    ;; First set `category' in the overlay
     ;;
-    (let ((alist (assoc-default (flymake--diag-type diagnostic)
-                                flymake-diagnostic-types-alist)))
-      (overlay-put ov 'category (assoc-default 'flymake-category alist))
-      (cl-loop for (k . v) in alist
-               unless (eq k 'category)
-               do (overlay-put ov k v)))
+    (overlay-put ov 'category
+                 (flymake--lookup-type-property type 'flymake-category))
+    ;; Now "paint" the overlay with all the other non-category
+    ;; properties.
+    (cl-loop
+     for (ov-prop . value) in
+     (append (reverse ; ensure ealier props override later ones
+              (flymake--lookup-type-property type 'flymake-overlay-control))
+             (alist-get type flymake-diagnostic-types-alist))
+     do (overlay-put ov ov-prop value))
     ;; Now ensure some essential defaults are set
     ;;
     (cl-flet ((default-maybe
                 (prop value)
-                (unless (or (plist-member (overlay-properties ov) prop)
-                            (let ((cat (overlay-get ov
-                                                    'flymake-category)))
-                              (and cat
-                                   (plist-member (symbol-plist cat) prop))))
-                  (overlay-put ov prop value))))
-      (default-maybe 'bitmap 'flymake-error-bitmap)
+                (unless (plist-member (overlay-properties ov) prop)
+                  (overlay-put ov prop (flymake--lookup-type-property
+                                        type prop value)))))
       (default-maybe 'face 'flymake-error)
       (default-maybe 'before-string
         (flymake--fringe-overlay-spec
-         (overlay-get ov 'bitmap)))
+         (flymake--lookup-type-property
+          type
+          'flymake-bitmap
+          (alist-get 'bitmap (alist-get type ; backward compat
+                                        flymake-diagnostic-types-alist)))))
       (default-maybe 'help-echo
         (lambda (window _ov pos)
           (with-selected-window window
@@ -825,7 +874,9 @@ The commands `flymake-goto-next-error' and
 diagnostics annotated in the buffer.
 
 The visual appearance of each type of diagnostic can be changed
-in the variable `flymake-diagnostic-types-alist'.
+by setting properties `flymake-overlay-control', `flymake-bitmap'
+and `flymake-severity' on the symbols of diagnostic types (like
+`:error', `:warning' and `:note').
 
 Activation or deactivation of backends used by Flymake in each
 buffer happens via the special hook
@@ -929,9 +980,8 @@ arg, skip any diagnostics with a severity less than `:warning'.
 If `flymake-wrap-around' is non-nil and no more next diagnostics,
 resumes search from top.
 
-FILTER is a list of diagnostic types found in
-`flymake-diagnostic-types-alist', or nil, if no filter is to be
-applied."
+FILTER is a list of diagnostic types, or nil, if no filter is to
+be applied."
   ;; TODO: let filter be a number, a severity below which diags are
   ;; skipped.
   (interactive (list 1
@@ -985,9 +1035,8 @@ prefix arg, skip any diagnostics with a severity less than
 If `flymake-wrap-around' is non-nil and no more previous
 diagnostics, resumes search from bottom.
 
-FILTER is a list of diagnostic types found in
-`flymake-diagnostic-types-alist', or nil, if no filter is to be
-applied."
+FILTER is a list of diagnostic types found in, or nil, if no
+filter is to be applied."
   (interactive (list 1 (if current-prefix-arg
                            '(:error :warning))
                      t))
diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index a09ca2f2f29..6f4a343310c 100644
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -5209,9 +5209,10 @@ be used."
 (defcustom python-flymake-msg-alist
   '(("\\(^redefinition\\|.*unused.*\\|used$\\)" . :warning))
   "Alist used to associate messages to their types.
-Each element should be a cons-cell (REGEXP . TYPE), where TYPE must be
-one defined in the variable `flymake-diagnostic-types-alist'.
-For example, when using `flake8' a possible configuration could be:
+Each element should be a cons-cell (REGEXP . TYPE), where TYPE
+should be a diagnostic type symbol like `:error', `:warning' or
+`:note'.  For example, when using `flake8' a possible
+configuration could be:
 
   ((\"\\(^redefinition\\|.*unused.*\\|used$\\)\" . :warning)
    (\"^E999\" . :error)