[elpa] externals/compat 503b13f1b1 8/8: Add compat-help as an infrastructure to manage relevant notes

[ELPA Syncer]

branch: externals/compat
commit 503b13f1b18fb1e4f3bdb66b6363dc44fd0a2ee2
Author: Philip Kaludercic <philipk@posteo.net>
Commit: Philip Kaludercic <philipk@posteo.net>

    Add compat-help as an infrastructure to manage relevant notes
    
    This is a voluntary library a developer might load to have notes
    inserted into help buffers of functions that might differ from their
    intuitive or expected behaviour.
---
 Makefile       |  3 ++-
 README.md      |  5 +++++
 compat-28.1.el |  5 +++++
 compat-help.el | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 compat-macs.el |  5 +++++
 5 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index f05370b63e..b9a6e8b4b6 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,8 @@
 .SUFFIXES: .el .elc
 
 EMACS = emacs
-BYTEC = compat-macs.elc \
+BYTEC = compat-help.elc \
+       compat-macs.elc \
        compat-24.4.elc \
        compat-25.1.elc \
        compat-26.1.elc \
diff --git a/README.md b/README.md
index 62042b6047..ccf80adc41 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,11 @@ Version 24.3 is chosen as the oldest version, because this 
is the
 newest version on CentOS 7. It is intended to preserve compatibility
 for at least as the Centos 7 reaches [EOL], 2024.
 
+If you are developing a package with compat.el in mind, consider
+loading `compat-help` (on your system, not in a package) to get
+relevant notes inserted into the help buffers of functions that are
+implemented or advised in compat.el.
+
 Installation
 ------------
 
diff --git a/compat-28.1.el b/compat-28.1.el
index f37f8c8025..032bb8bc3e 100644
--- a/compat-28.1.el
+++ b/compat-28.1.el
@@ -43,6 +43,10 @@ HAYSTACK and defaults to zero (start at the beginning).
 It must be between zero and the length of HAYSTACK, inclusive.
 
 Case is always significant and text properties are ignored."
+  :note "Prior to Emacs 27 `string-match' has issues handling
+multibyte regular expressions.  As the compatibility function
+for `string-search' is implemented via `string-match', these
+issues are inherited."
   (when (and start-pos (< start-pos 0))
     (signal 'args-out-of-range (list start-pos)))
   (save-match-data
@@ -109,6 +113,7 @@ positive number N, it means to run GC if more than 1/Nth of 
the
 allocations needed to trigger automatic allocation took place.
 Therefore, as N gets higher, this is more likely to perform a GC.
 Returns non-nil if GC happened, and nil otherwise."
+  :note "For releases of Emacs before version 28, this function will do 
nothing."
   ;; Do nothing
   nil)
 
diff --git a/compat-help.el b/compat-help.el
new file mode 100644
index 0000000000..8e9942d160
--- /dev/null
+++ b/compat-help.el
@@ -0,0 +1,57 @@
+;;; compat-help.el --- Documentation for compat functions  -*- 
lexical-binding: t; -*-
+
+;; Copyright (C) 2022  Philip Kaludercic
+
+;; Author: Philip Kaludercic <philipk@posteo.net>
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Load this file to insert `compat'-relevant documentation next to
+;; the regular documentation of a symbol.
+
+;;; Code:
+
+(defun compat---describe (symbol)
+  "Insert documentation for SYMBOL if it has compatibility code."
+  (let ((compat (get symbol 'compat-def)))
+    (when compat
+      (let ((doc (get compat 'compat-doc))
+            (start (point)))
+        (when doc
+          (insert "There is a ")
+          (insert-button
+           "compatibility notice"
+           'action (let ((type (get compat 'compat-type)))
+                     (cond
+                      ((memq type '(func macro advice))
+                       #'find-function)
+                      ((memq type '(variable))
+                       #'find-variable)
+                      ((error "Unknown type"))))
+           'button-data compat)
+          (insert (format " for %s (for versions of Emacs before %s):"
+                          (symbol-name symbol)
+                          (get compat 'compat-version)))
+          (add-text-properties start (point) '(face bold))
+          (newline 2)
+          (insert (substitute-command-keys doc))
+          (fill-region start (point))
+          (newline 2))))))
+
+(add-hook 'help-fns-describe-function-functions #'compat---describe)
+
+(provide 'compat-help)
+;;; compat-help.el ends here
diff --git a/compat-macs.el b/compat-macs.el
index c7878d043a..43e2ab9528 100644
--- a/compat-macs.el
+++ b/compat-macs.el
@@ -61,6 +61,9 @@ attributes are handled, all others are ignored:
 - :realname :: Manual specification of a \"realname\" to use for
   the compatibility definition (symbol).
 
+- :notes :: Additional notes that a developer using this
+  compatibility function should keep in mind.
+
 TYPE is used to set the symbol property `compat-type' for NAME."
   (let* ((min-version (plist-get attr :min-version))
          (max-version (plist-get attr :max-version))
@@ -100,6 +103,8 @@ TYPE is used to set the symbol property `compat-type' for 
NAME."
     `(progn
        (put ',realname 'compat-type ',type)
        (put ',realname 'compat-version ,version)
+       (put ',realname 'compat-doc ,(plist-get attr :note))
+       (put ',name 'compat-def ',realname)
        ,(funcall def-fn realname version)
        ,(if feature
             ;; See https://nullprogram.com/blog/2018/02/22/: