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

[martin rudalics]

> 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.

martin