From ee1034422b0c84722a237ab6fdd410ab74674ee6 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Tue, 7 Jan 2025 17:20:22 +0200
Subject: [PATCH] ; Improve documentation of function-type display

* etc/NEWS: Document 'help-display-function-type'.

* doc/lispref/functions.texi (Declare Form):
* doc/lispref/objects.texi (Type Specifiers):
* doc/emacs/help.texi (Name Help): Better indexing of function
types.  (Bug#65288)
---
 doc/emacs/help.texi        | 3 ++-
 doc/lispref/functions.texi | 1 +
 doc/lispref/objects.texi   | 1 +
 etc/NEWS                   | 8 ++++++--
 4 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 2e0eb0d6459..5c2eabb02d6 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -323,7 +323,8 @@ yet further information is often reachable by clicking or typing
 @key{RET} on emphasized parts of the text.
 
 @cindex function type specifier
-
+@cindex declared type of a function
+@cindex inferred type of a function
 The function type, if known, is expressed with a @dfn{function type
 specifier} (@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference
 Manual}), it will be specified if the type was manually declared by a
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index dc9443b69bc..6f65ff95c44 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -2726,6 +2726,7 @@ function.  This allows function-level control of the safety level used
 for the code emitted for the function (@pxref{Native-Compilation
 Variables}).
 
+@cindex function type declaration
 @item (ftype @var{type} &optional @var{function})
 Declare @var{type} to be the type of this function.  This is used for
 documentation by @code{describe-function}.  Also it can be used by the
diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi
index 3bd5a4528b0..630765213a2 100644
--- a/doc/lispref/objects.texi
+++ b/doc/lispref/objects.texi
@@ -1545,6 +1545,7 @@ The @code{not} type specifier defines any type except the specified one.
 The @code{member} type specifier allows to specify a type that includes
 only the explicitly listed values.
 
+@cindex declared type of a function
 @item (function (@var{arg-1-type} @dots{} @var{arg-n-type}) @var{return-type})
 The @code{function} type specifier is used to describe the argument
 types and the return type of a function.  Argument types can be interleaved
diff --git a/etc/NEWS b/etc/NEWS
index 6b2831e3809..31a0c4938ad 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -481,9 +481,13 @@ This user option controls outline visibility in the output buffer of
 'describe-bindings' when 'describe-bindings-outline' is non-nil.
 
 ---
-*** 'describe-function' shows the function inferred type when available.
+*** 'describe-function' shows the function's inferred type when available.
 For native compiled Lisp functions, 'describe-function' prints (after
-the signature) the automatically inferred function type as well.
+the signature) the automatically inferred function type as well.  If the
+function's type was explicitly declared (via the 'declare' form's
+'ftype' property), 'describe-function' shows the declared type.  This is
+controlled by the new user option 'help-display-function-type', which is
+by default t; customize to nil to disable function type display.
 
 ---
 *** 'describe-function' now shows the type of the function object.