- What I did

Add a new zsh function to the completion file contrib/completion/zsh/_docker.

The bulk of the function is copy and paste from the documentation of
--cap-add (Subject to review: I barely read through them, assuming the docs on the web are a good initial version. I did not investigate if the list of capabilities can be obtained in an automated manner.).

The function is called when tab completing docker run --cap-add= (or drop).

The suggested completion should look like that (depending on a user's configuration of zsh's tab completion):

>> docker run --cap-add=
special capability value:
ALL  -- enable/disable all capabilities
off by default capabilities:
AUDIT_CONTROL    -- Enable and disable kernel auditing; change auditing filter rules; retrieve auditing st
BLOCK_SUSPEND    -- Employ features that can block system suspend.
DAC_READ_SEARCH  -- Bypass file read permission checks and directory read and execute permission checks.
IPC_LOCK         -- Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)).
...

The function checks:

• if --cap-add or --cap-drop is completed. In the former case, off-by-default capabilities are suggested. In the latter case on-by-default capabilities are suggested (I took that idea from the bash completion).

• if --cap-add=ALL or --cap-drop=ALL are present on the current command line. If --cap-add=ALL is present in the command line, then --cap-drop= will also suggest off-by-default capabilities (and vice versa). This should look something like that:

special capability value:
ALL  -- enable/disable all capabilities
on by default capabilities:
AUDIT_WRITE       -- Write records to kernel auditing log.
CHOWN             -- Make arbitrary changes to file UIDs and GIDs (see chown(2)).
...
off by default capabilities:
AUDIT_CONTROL    -- Enable and disable kernel auditing; change auditing filter rules; retrieve auditing st
BLOCK_SUSPEND    -- Employ features that can block system suspend.
DAC_READ_SEARCH  -- Bypass file read permission checks and directory read and execute permission checks.
...

The function does not check any other already-present settings of --cap-add. I.e. docker run --cap-add=BLOCK_SUSPEND --cap-add=<TAB> will still suggest BLOCK_SUSPEND as option.
(Subject for discussion. My impression is it's not worth increasing the complexity of the completion function for such a corner case.)

- How I did it

Sticking to zsh's builtin features. I use the opt_args associative array to
detect what's already specified in --cap-add on the command line. If the
option is given multiple times, $opt_args[--cap-add] will be colon separated.
I didn't add any logic to handle that case but rely on *ALL* matching exactly
the ALL value and ALL doesn't occur in any other capability.

- How to verify it

Typed interactively a few examples

docker run --cap-add=<TAB>

docker run --cap-drop=<TAB>

docker run --cap-add=ALL --cap-drop=<TAB>

docker run --cap-add=DAC_READ_SEARCH --cap-add=ALL --cap-add=MAC_OVERRIDE --cap-drop=<TAB>

- Description for the changelog

Add suggestions for docker run --cap-{add,drop}=<TAB> in the zsh completion

- A picture of a cute animal (not mandatory but encouraged)