bug#34588: 27.0.50; Doc of write-contents-functions: arguments?

[Stefan Kangas]

close 34588 28.1
thanks

martin rudalics <rudalics@gmx.at> writes:

>> Maybe Richard meant we should document that something should _not_ be
>> called "-hook" when it is called with
>> `run-hook-with-args-until-success'?  That _would_ have answered my
>> question, and stating that as a convention would make sense to me.
>
> The Elisp manual already says that as
>
>      If the hook variable's name does not end with `-hook', that
>   indicates it is probably an "abnormal hook".  That means the hook
>   functions are called with arguments, or their return values are used in
>   some way.  The hook's documentation says how the functions are called.
>   You can use `add-hook' to add a function to an abnormal hook, but you
>   must write the function to follow the hook's calling convention.  By
>   convention, abnormal hook names end in `-functions'.
>
> and
>
>      The variables whose names end in `-functions' are usually "abnormal
>   hooks" (some old code may also use the deprecated `-hooks' suffix);
>   their values are lists of functions, but these functions are called in
>   a special way (they are passed arguments, or their return values are
>   used).  The variables whose names end in `-function' have single
>   functions as their values.
>
> and for 'write-contents-functions' it says that
>
>      If any of the functions in this hook returns non-`nil', the file
>      is considered already written and the rest are not called and
>      neither are the functions in `write-file-functions'.
>
> so the naming convention is preserved and everything should have been
> clear.  I believe that due to how the documentation is written,
> readers intuitively pay less attention to the "or their return values
> are used in some way" and "or their return values are used" phrases.

I clarified this to:

    "That means one of two things: either that the hook functions are
    called with arguments, or that their their return values are used in
    some way."

And:

    "Their values are lists of functions, but these functions are called
    in a special way: they are either passed arguments, or their return
    values are used in some way."

This change has been pushed to emacs-28 (commit 4fd5c8df67).

I believe this is sufficiently clear, so I'm closing this bug report.
Feel free to install any further tweaks.  Thanks.