[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-29 efcbf0b5abf: Add use cases of (fn) documentation facility.
From: |
Eli Zaretskii |
Subject: |
emacs-29 efcbf0b5abf: Add use cases of (fn) documentation facility. |
Date: |
Sat, 16 Dec 2023 07:57:57 -0500 (EST) |
branch: emacs-29
commit efcbf0b5abfed8bbf767209a913b5e25270596a4
Author: Jeremy Bryant <jb@jeremybryant.net>
Commit: Eli Zaretskii <eliz@gnu.org>
Add use cases of (fn) documentation facility.
* doc/lispref/functions.texi (Function Documentation): Add examples.
(Bug#67499)
Co-authored-by: Eli Zaretskii <eliz@gnu.org>
---
doc/lispref/functions.texi | 33 +++++++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index e646e7c8b0a..34a568b728e 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -533,6 +533,39 @@ Instead, use the @code{advertised-calling-convention}
declaration
compiler emit a warning message when it compiles Lisp programs which
use the deprecated calling convention.
+@ifnottex
+The @code{(fn)} feature is typically used in the following situations:
+
+@itemize @minus
+@item To spell out arguments and their purposes in a macro or a function.
Example:
+
+@example
+(defmacro lambda (&rest cdr)
+ "@dots{}
+\(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"@dots{})
+@end example
+
+@item To provide a more detailed description and names of arguments. Example:
+
+@example
+(defmacro macroexp--accumulate (var+list &rest body)
+ "@dots{}
+\(fn (VAR LIST) BODY@dots{})"
+ (declare (indent 1))
+ (let ((var (car var+list))
+ (list (cadr var+list))
+@dots{})))
+@end example
+
+@item To better explain the purpose of a @code{defalias}. Example:
+
+@example
+(defalias 'abbrev-get 'get
+ "@dots{}
+\(fn ABBREV PROP)")
+@end example
+@end ifnottex
+
@cindex computed documentation string
@kindex :documentation
Documentation strings are usually static, but occasionally it can be
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-29 efcbf0b5abf: Add use cases of (fn) documentation facility.,
Eli Zaretskii <=