From 3f427ea7e437a83b5e62121032d0352abf6b4bd8 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Sun, 3 Dec 2023 21:32:01 +0000 Subject: [PATCH] Add use cases of (fn) documentation facility. * doc/lispref/functions.texi (Function Documentation): Add examples Co-authored-by: Eli Zaretskii --- 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 @@ Function Documentation 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 -- 2.42.0