Merge pull request #19929 from Homebrew/cask-shell-completions

cask: document shell completion stanzas

Author: EricFromCanada

Library/Homebrew/cask/artifact/shellcompletion.rb

@@ -6,11 +6,6 @@
 module Cask
   module Artifact
     class ShellCompletion < Symlinked
-      sig { params(cask: Cask, source: T.any(String, Pathname)).returns(ShellCompletion) }
-      def self.from_args(cask, source)
-        new(cask, source)
-      end
-
       sig { params(_: T.any(String, Pathname)).returns(Pathname) }
       def resolve_target(_)
         raise CaskInvalidError, "Shell completion without shell info"

Library/Homebrew/rubocops/cask/constants/stanza.rb

@@ -40,6 +40,9 @@ module Constants
             :installer,
             :binary,
             :manpage,
+            :bash_completion,
+            :fish_completion,
+            :zsh_completion,
             :colorpicker,
             :dictionary,
             :font,

docs/Cask-Cookbook.md

@@ -67,6 +67,9 @@ Having a common order for stanzas makes casks easier to update and parse. Below
     installer
     binary
     manpage
+    bash_completion
+    fish_completion
+    zsh_completion
     colorpicker
     dictionary
     font
@@ -130,6 +133,9 @@ Each cask must declare one or more *artifacts* (i.e. something to install).
 | [`installer`](#stanza-installer) | yes                           | Describes an executable which must be run to complete the installation. |
 | [`binary`](#stanza-binary)       | yes                           | Relative path to a Binary that should be linked into the `$(brew --prefix)/bin` folder on installation. |
 | `manpage`                        | yes                           | Relative path to a Man Page that should be linked into the respective man page folder on installation, e.g. `/opt/homebrew/share/man/man3` for `my_app.3`. |
+| `bash_completion`                | yes                           | Relative path to a Bash completion file that should be linked into the `$(brew --prefix)/etc/bash_completion.d` folder on installation. |
+| `fish_completion`                | yes                           | Relative path to a fish completion file that should be linked into the `$(brew --prefix)/share/fish/vendor_completions.d` folder on installation. |
+| `zsh_completion`                 | yes                           | Relative path to a Zsh completion file that should be linked into the `$(brew --prefix)/share/zsh/site-functions` folder on installation. |
 | `colorpicker`                    | yes                           | Relative path to a ColorPicker plugin that should be moved into the `~/Library/ColorPickers` folder on installation. |
 | `dictionary`                     | yes                           | Relative path to a Dictionary that should be moved into the `~/Library/Dictionaries` folder on installation. |
 | `font`                           | yes                           | Relative path to a Font that should be moved into the `~/Library/Fonts` folder on installation. |
@@ -199,7 +205,7 @@ artifact "sapmachine-jdk-#{version}.jdk", target: "/Library/Java/JavaVirtualMach
 
 #### *target* works on most artifact types
 
-The `target:` key works similarly for most cask artifacts, such as `app`, `binary`, `colorpicker`, `dictionary`, `font`, `input_method`, `internet_plugin`, `keyboard_layout`, `prefpane`, `qlplugin`, `mdimporter`, `screen_saver`, `service`, `suite`, `audio_unit_plugin`, `vst_plugin`, `vst3_plugin`, and `artifact`.
+The `target:` key works similarly for most cask artifacts, such as `app`, `binary`, `bash_completion`, `fish_completion`, `zsh_completion`, `colorpicker`, `dictionary`, `font`, `input_method`, `internet_plugin`, `keyboard_layout`, `prefpane`, `qlplugin`, `mdimporter`, `screen_saver`, `service`, `suite`, `audio_unit_plugin`, `vst_plugin`, `vst3_plugin`, and `artifact`.
 
 #### *target* should only be used in select cases