Over on https://bugs.debian.org/1059771 users are confused by the documentation for --batch. gpg(1) says of --batch:

Use batch mode. Never ask, do not allow interactive commands. --no-batch disables this option. Note that even with a filename given on the command line, gpg might still need to read from STDIN (in particular if gpg figures that the input is a detached signature and no data file has been specified). Thus if you do not want to feed data via STDIN, you should connect STDIN to /dev/null.

It is highly recommended to use this option along with the options --status-fd and --with-colons for any unattended use of gpg. Should not be used in an option file.

The user confusion comes in because even in batch mode, gpg might talk to gpg-agent and gpg-agent might decide to ask the user for a password via pinentry. This contradicts the "never ask" part of the documentation above.

The easiest way to align user expectations is probably to add a note in the manpage explaining that asking for passwords is orthogonal to --batch, and that if an invocation wants to avoid prompting the user for passwords, they need something additional, like --pinentry-mode=loopback.