[elpa] externals/compat d8cb8cc5ae 4/5: Improve commentary

[ELPA Syncer]

branch: externals/compat
commit d8cb8cc5ae91646ac373a73a7a1facf34ba16945
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@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: