From 8ff1589630cb723857b6886c56ac836a333d69e5 Mon Sep 17 00:00:00 2001 From: Jeremy Bryant Date: Mon, 27 Nov 2023 23:18:03 +0000 Subject: [PATCH] Add use cases of (fn) documentation facility. * doc/lispref/functions.texi (Function Documentation): Add examples --- doc/lispref/functions.texi | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index e646e7c8b0a..fe7ed78d568 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -533,6 +533,42 @@ Function Documentation compiler emit a warning message when it compiles Lisp programs which use the deprecated calling convention. +@ifnottex +In this section we outline examples of the use of the @code{(fn)} facility. + +@itemize @minus +@item Explaining @code{&rest} in a @code{defmacro}: + +@file{subr.el}: @code{lambda}. This is a canonical example where the +arguments are unclear, and the @code{(fn)} facility helps to spell out +the arglist @code{&rest}. + +@example +(defmacro lambda (&rest cdr) + "Return an anonymous function. (...) +\(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"...) +@end example + +@item Explaining @code{&rest} in a @code{defun}, concretely: + +@file{keymap.el} : @code{define-keymap}. The single parameter +@code{&rest definitions} list is not clear, so the @code{fn} facility +explains it. + +@item Renaming parameters to give context in a @code{defalias}: + +@file{abbrev.el} : @code{(abbrev-get)}. Here @code{get}'s general argument of +@code{symbol} is renamed as @code{abbrev}. + +@item Naming list constituents in a required argument: + +@file{macroexp.el} : @code{macroexp--accumulate}. The argument of +@code{var+list}, which is more clearly described as @code{(var list)}. +@end itemize + +@end ifnottex + + @cindex computed documentation string @kindex :documentation Documentation strings are usually static, but occasionally it can be -- 2.42.0