[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#24740: 26.0.50; Bad signature for alist-get in elisp manual
From: |
Eli Zaretskii |
Subject: |
bug#24740: 26.0.50; Bad signature for alist-get in elisp manual |
Date: |
Thu, 20 Oct 2016 10:49:04 +0300 |
> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: eliz@gnu.org, a.lloyd.flanagan@gmail.com
> Date: Thu, 20 Oct 2016 01:39:15 +0200
>
> > -@defun alist-get key value &optional default remove
> > +@defun alist-get key alist &optional default remove
> > This function is like @code{assq}, but instead of returning the entire
> > -association for @var{key}, @code{(@var{key} . @var{value})}, it
> > -returns just the @var{value}. If @var{key} is not found in
> > -@var{alist} it returns @var{default}.
> > +association for @var{key} in @var{alist},
> > +@w{@code{(@var{key} . @var{value})}}, it returns just the @var{value}.
> ^^^^^^^^^^^
> > +If @var{key} is not found in @var{alist}, it returns @var{default}.
>
> Shouldn't the text be "it returns just the value", i.e. without the
> markup, since `value' is no longer a formal argument of the function
> signature?
@var is not only for formal arguments, it's for any symbol which
stands for something else. That is why @var is also used in the cons
cell description; it is not because KEY and VALUE happen to appear in
the function argument list.
For example, we use @var in text such as this:
A value of the form @code{(@var{num} . @var{expr})} stands for the
product of the values of @var{num} and @var{expr}.
These NUM and EXPR are not formal arguments of any function.
The Texinfo manual says:
Use the '@var' command to indicate metasyntactic variables. A
"metasyntactic variable" is something that stands for another piece of
text. For example, you should use a metasyntactic variable in the
documentation of a function to describe the arguments that are passed to
that function.
IOW, the function arguments use case is just one example of where @var
should be used.