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

[Eli Zaretskii]

> From: Jeremy Bryant <jb@jeremybryant.net>
> Cc: 67499@debbugs.gnu.org
> Date: Wed, 29 Nov 2023 23:29:58 +0000
> 
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > 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.

Thanks.  I actually had in mind an even shorter variant:

  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

WDYT?

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

We don't include pointers to our sources in the manual, except in very
rare cases.  I'm not sure we need to do it here.  One disadvantage of
having pointers to files is that we need to keep the pointers
up-to-date as development continues.

Thanks.