Subject: Re: bug#67499: [PATCH] Add use cases of (fn) documentation facility.

From: Jeremy Bryant <[email-masked]>
Date: Wed, 29 Nov 2023 23:29:58 +0000

Eli Zaretskii <[email-masked]> writes:

>> Date: Mon, 27 Nov 2023 23:30:33 +0000
>> From:  Jeremy Bryant via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <[email-masked]>
>> 
>> I have written a proposed addition to the Elisp manual.  In now-closed
>> bug 66928, there was a discussion related to the use of \(fn) in doc
>> strings, and I have drafted some examples to explain how this facility
>> could be used.  The addition is presented as @ifnottex... in order to
>> reduce the cost of the printed manual.
>> 
>> Feedback welcome on draft before I refine further, on conventions, section of
>> manual, style etc.
>
> Thanks.
>
> I wonder whether we need this to be said in so many words.  Can't we
> instead just enumerate the uses, describing each one in a couple of
> sentences, and format that as, say, an @itemize'd list?  IOW, do we
> really need to show an explicit example for each use?  Examples are
> useful when an example is worth a thousand words, which is not the
> case here, I think.

Understood, and substantially rewritten as attached, as an @itemize'd list.

The reader can then use find-function at point in the info manual, to
 read the code.

>From 8ff1589630cb723857b6886c56ac836a333d69e5 Mon Sep 17 00:00:00 2001
From: Jeremy Bryant <[email-masked]>
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

>
> A minor stylistic comments:
>
>> +In subr.el, the definition of lambda is as below, and the (fn) facility
>       ^^^^^^^                    ^^^^^^
> File names should have the @file markup, and symbols and other code
> fragments (like "&rest" and "defun") should have the @code markup.

Added @file and @code for all applicable markups.

In summary, the new compact text should help new contributors understand how the
(fn) magic can be used.

If it's not good to install, please let me know what to do.