branch: externals/compat
commit d8cb8cc5ae91646ac373a73a7a1facf34ba16945
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@daniel-mendler.de>
Improve commentary
---
compat-macs.el | 7 ++++++-
compat.el | 29 ++++++++++++++++-------------
2 files changed, 22 insertions(+), 14 deletions(-)
diff --git a/compat-macs.el b/compat-macs.el
index 2e07399fb1..4b2368bf17 100644
--- a/compat-macs.el
+++ b/compat-macs.el
@@ -17,7 +17,12 @@
;;; Commentary:
-;; These macros are used to define compatibility functions and macros.
+;; This file provides *internal* macros, which are used by Compat to
+;; facilitate the definition of compatibility functions, macros and
+;; variables. The `compat-macs' feature should never be loaded at
+;; runtime in your Emacs and will only be used during byte
+;; compilation. Every definition provided here should be considered
+;; internal and may change any time between Compat releases.
;;; Code:
diff --git a/compat.el b/compat.el
index b7daebd8a3..076c0cfa06 100644
--- a/compat.el
+++ b/compat.el
@@ -24,22 +24,25 @@
;;; Commentary:
-;; To allow for the usage of Emacs functions and macros that are
-;; defined in newer versions of Emacs, compat.el provides definitions
-;; that are installed ONLY if necessary. If Compat is installed on a
-;; recent version of Emacs, all of the definitions are disabled at
-;; compile time, such that no negative performance impact is incurred.
-;; These reimplementations of functions and macros are at least
-;; subsets of the actual implementations. Be sure to read the
-;; documentation string to make sure.
+;; Compat is the Elisp forwards compatibility library, which provides
+;; definitions introduced in newer Emacs versions. The definitions
+;; are only installed if necessary for your current Emacs version. If
+;; Compat is compiled on a recent version of Emacs, all of the
+;; definitions are disabled at compile time, such that no negative
+;; performance impact is incurred. The provided compatibility
+;; implementations of functions and macros are at least subsets of the
+;; actual implementations. Be sure to read the documentation string
+;; and the Compat manual.
;;
;; Not every function provided in newer versions of Emacs is provided
-;; here. Some depend on new features from the core, others cannot be
-;; implemented to a meaningful degree. Please consult the Compat
+;; here. Some depend on new features from the C core, others cannot
+;; be implemented to a meaningful degree. Please consult the Compat
;; manual for details regarding the usage of the Compat library and
-;; the provided functionality. The main audience for this library are
-;; not regular users, but package maintainers. Therefore no commands,
-;; user-facing modes or user options are implemented here.
+;; the provided functionality.
+
+;; The main audience for this library are not regular users, but
+;; package maintainers. Therefore no commands, user-facing modes or
+;; user options are implemented here.
;;; Code:
