Improve ZSH completions handling

- Only display the completions caveats from the current shell (assuming
  it's one of Bash, ZSH or Fish)
- If the completions location isn't in the ZSH `FPATH` then link to the
  documentation explaining how to do so.

Fixes https://github.com/Homebrew/brew/issues/8984

Library/Homebrew/caveats.rb

@@ -26,9 +26,20 @@ class Caveats
       f.build = build
     end
     caveats << keg_only_text
-    caveats << function_completion_caveats(:bash)
+
-    caveats << function_completion_caveats(:zsh)
+    valid_shells = [:bash, :zsh, :fish].freeze
-    caveats << function_completion_caveats(:fish)
+    current_shell = Utils::Shell.preferred || Utils::Shell.parent
+    shells = if current_shell.present? &&
+                (shell_sym = current_shell.to_sym) &&
+                valid_shells.include?(shell_sym)
+      [shell_sym]
+    else
+      valid_shells
+    end
+    shells.each do |shell|
+      caveats << function_completion_caveats(shell)
+    end
+
     caveats << plist_caveats
     caveats << elisp_caveats
     caveats.compact.join("\n")
@@ -117,10 +128,20 @@ class Caveats
           #{root_dir}/etc/bash_completion.d
       EOS
     when :zsh
-      <<~EOS
+      site_functions = root_dir/"share/zsh/site-functions"
+      zsh_caveats = +<<~EOS
         zsh #{installed.join(" and ")} have been installed to:
-          #{root_dir}/share/zsh/site-functions
+          #{site_functions}
       EOS
+      unless PATH.new(ENV["HOMEBREW_FPATH"]).to_a.include?(site_functions.to_s)
+        zsh_caveats << <<~EOS
+
+          #{site_functions} is not in your zsh FPATH!
+          Add it by following these steps:
+            #{Formatter.url("https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh")}
+        EOS
+      end
+      zsh_caveats.freeze
     when :fish
       fish_caveats = +"fish #{installed.join(" and ")} have been installed to:"
       fish_caveats << "\n  #{root_dir}/share/fish/vendor_completions.d" if completion_installed

Library/Homebrew/test/caveats_spec.rb

@@ -188,6 +188,8 @@ describe Caveats do
       before do
         allow_any_instance_of(Pathname).to receive(:children).and_return([Pathname.new("child")])
         allow_any_instance_of(Object).to receive(:which).with(any_args).and_return(Pathname.new("shell"))
+        allow(Utils::Shell).to receive(:preferred).and_return(nil)
+        allow(Utils::Shell).to receive(:parent).and_return(nil)
       end
 
       it "gives dir where bash completions have been installed" do

bin/brew

@@ -62,7 +62,7 @@ HOMEBREW_LIBRARY="$HOMEBREW_REPOSITORY/Library"
 
 # Copy and export all HOMEBREW_* variables previously mentioned in
 # manpage or used elsewhere by Homebrew.
-for VAR in BROWSER DISPLAY EDITOR NO_COLOR PATH
+for VAR in BROWSER DISPLAY EDITOR NO_COLOR PATH FPATH
 do
   # Skip if variable value is empty.
   [[ -z "${!VAR}" ]] && continue