branch: externals/compat
commit 82656eaed5cfeba2840eaa044ef82c72e0cfc60c
Author: Daniel Mendler <[email protected]>
Commit: Daniel Mendler <[email protected]>
Add documentation
---
compat.el | 2 +-
compat.texi | 15 +++++++++++++++
2 files changed, 16 insertions(+), 1 deletion(-)
diff --git a/compat.el b/compat.el
index dee0a4fec3..9d041e6f39 100644
--- a/compat.el
+++ b/compat.el
@@ -51,7 +51,7 @@ FUN, the symbol FUN is returned itself."
`#',(if (fboundp compat) compat fun)))
(defmacro compat-call (fun &rest args)
- "Call compatibility function FUN with ARGS.
+ "Call compatibility function or macro FUN with ARGS.
See `compat-function' for the compatibility function resolution."
(let ((compat (intern (format "compat--%s" fun))))
diff --git a/compat.texi b/compat.texi
index 805dca4278..52a03b3b2f 100644
--- a/compat.texi
+++ b/compat.texi
@@ -143,6 +143,21 @@ call these definitions ``Explicit Definitions''. In
contrast,
(mapcan FUNCTION SEQUENCE) ;; Implicit
@end example
+@defmac compat-call FUN &rest ARGS
+This macro calls the compatibility function FUN with ARGS. Many
+functions provided by Compat can be called directly without this
+macro. However in the case where Compat provides an alternative
+version of an exisiting function, the function call has to go through
+@code{compat-call}. This happens for example when the calling
+convention of a function has changed.
+@end defmac
+
+@defmac compat-function FUN
+This macro returns the compatibility function symbol for FUN. See
+@code{compat-call} for a more convenient macro to directly call
+compatibility functions.
+@end defmac
+
If you intend to use a compatibility function in your code it is
strongly recommended that you check the tests in
@file{compat-tests.el}. Alternatively grep the Compat code for
