bug#81643: 32.0.50; use-package :hook is not the same as :init add-hook

> Date: Wed, 19 Aug 2026 11:31:00 +0200
> Cc: Eli Zaretskii <[email protected]>, [email protected],
>  [email protected]
> From: Björn A. Lindqvist <[email protected]>
> 
>  >> I think the documentation is very confusing. For example:
>  >
>  >>      (use-package company
>  >>      :commands company-mode
>  >>      :init
>  >>      (add-hook 'prog-mode-hook #'company-mode))
>  >
>  >> Why is the hook function named company-mode?
>  >
>  > Because that the name of the function used to turn on company-mode.
> 
> How can you know that if you are not familiar with company-mode? Once
> you "get" it--that all examples are about turning on input completion
> when another mode loads ("setting up autoloads"), it makes
> sense. Examples would be clearer if the function was called
> #'my-random-hook-fun or something.

There must be some kind of misunderstanding here, perhaps mine: the
function you add to a hook variable is not a hook function, it's a
"normal" function that is _called_ by the run-hooks machinery.

So in the above example, company-mode is NOT a "hook function", it's a
function that we want to be called whenever prog-mode-hook hook is
run.  And the fact that a command to turn ON Company mode is called
"company-mode" is trivial to know: that's our naming convention for
functions that turn ON a mode.

Or what am I missing?