all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Visuwesh <visuweshm@gmail.com>
To: Stefan Kangas <stefankangas@gmail.com>
Cc: 59379@debbugs.gnu.org, Stefan Monnier <monnier@iro.umontreal.ca>
Subject: bug#59379: 29.0.50; `define-advice' documentation needs improving
Date: Sat, 19 Nov 2022 20:14:32 +0530	[thread overview]
Message-ID: <8735afatrj.fsf@gmail.com> (raw)
In-Reply-To: <CADwFkmm2bxVzv+5DxA54Ywv3WWPjXBLBstdoMx-hbzepBpMiJw@mail.gmail.com> (Stefan Kangas's message of "Sat, 19 Nov 2022 05:52:41 -0800")

[சனி நவம்பர் 19, 2022] Stefan Kangas wrote:

> Visuwesh <visuweshm@gmail.com> writes:
>
>>> 3. This is its argument list:
>>>
>>>    (define-advice SYMBOL (HOW LAMBDA-LIST &optional NAME DEPTH) &rest
>>>    BODY)
>>>
>>>    The HOW, LAMBDA-LIST, NAME, DEPTH parameters are not documented in
>>>    the docstring, nor in the info manual.
>>
>> HOW, LAMBDA-LIST, NAME, and DEPTH arguments become clear when once looks
>> up the add-function docstring, and the docstring already mentions
>> add-function.
>
> Then that should be explicitly stated.

Is that not already spelt out?

    Define an advice and add it to function named SYMBOL.
    See ‘advice-add’ and ‘add-function’ for explanation on the
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    arguments.  Note if NAME is nil the advice is anonymous;
    ^^^^^^^^^^
    otherwise it is named ‘SYMBOL@NAME’.

> And LAMBDA-LIST is not explained there either, AFAICT.

Reading the advice-add's document should tell what it means but I might
be biased here.

>>> 5. The documentation of NAME says that: "The advice is an anonymous
>>>    function if NAME is ‘nil’ or a function named ‘symbol@name’."
>>>
>>>    I struggle with parsing this sentence.  It sounds like it is saying
>>>    that, if I want an anonymous function, I should define a function
>>>    named `symbol@name' (substituting `symbol' and `name') and then pass
>>>    that argument as the NAME argument?  But then the function is not
>>>    anonymous?
>>
>> Would a comma help before the "or"? i.e.,
>>
>>     The advice is an anonymous function if NAME is ‘nil’, or a function
>>     named ‘symbol@name’.
>
> So it can be either nil or a symbol?  How do I actually use it?

Yes.  See below for an example with a non-nil NAME

    (define-advice file-cache-file-name (:filter-return (filename) vz/add-slash-if-directory)
      "Add a trailing slash if FILENAME is a directory."
      (if (file-directory-p filename)
          (concat filename "/")
        filename))

which creates a function file-cache-file-name@vz/add-slash-if-directory.
But if NAME was nil, then there would be no named function but rather a
lambda that gets added as an advice (which is hard to remove later).

>> Changing symbol@name to SYMBOL@NAME like in the docstring will make it
>> clearer, I think.  If still not clear, the following happens in the case
>> of NAME being nil vs. non-nil
>>
>>     NAME nil ==> (advice-add SYMBOL HOW (lambda LAMBDA-LIST BODY) ...)
>>     NAME non-nil ==> (advice-add SYMBOL HOW (defun SYMBOL@NAME LAMBDA-LIST BODY) ...)
>
> This all needs to be explained clearly in the documentation.

Again, it seems obvious to me.





  reply	other threads:[~2022-11-19 14:44 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-11-19  7:26 bug#59379: 29.0.50; `define-advice' documentation needs improving Stefan Kangas
2022-11-19 12:23 ` Visuwesh
2022-11-19 13:52   ` Stefan Kangas
2022-11-19 14:44     ` Visuwesh [this message]
2022-11-19 15:34   ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2024-02-08  6:46   ` Visuwesh
2024-02-08 13:49     ` Visuwesh
2024-02-08 13:54       ` Eli Zaretskii

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=8735afatrj.fsf@gmail.com \
    --to=visuweshm@gmail.com \
    --cc=59379@debbugs.gnu.org \
    --cc=monnier@iro.umontreal.ca \
    --cc=stefankangas@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.