Merge pull request #8339 from reitermarkus/documentation

Improve documentation and add `@api private` to internal classes.

Library/Homebrew/cask/artifact/internet_plugin.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `internet_plugin` stanza.
+    #
+    # @api private
     class InternetPlugin < Moved
     end
   end

Library/Homebrew/cask/artifact/manpage.rb

@@ -4,6 +4,9 @@ require "cask/artifact/symlinked"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `manpage` stanza.
+    #
+    # @api private
     class Manpage < Symlinked
       attr_reader :section
 

Library/Homebrew/cask/artifact/mdimporter.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `mdimporter` stanza.
+    #
+    # @api private
     class Mdimporter < Moved
       def self.english_name
         "Spotlight metadata importer"

Library/Homebrew/cask/artifact/moved.rb

@@ -4,6 +4,9 @@ require "cask/artifact/relocated"
 
 module Cask
   module Artifact
+    # Superclass for all artifacts which are installed by moving them to the target location.
+    #
+    # @api private
     class Moved < Relocated
       def self.english_description
         "#{english_name}s"

Library/Homebrew/cask/artifact/pkg.rb

@@ -10,6 +10,9 @@ using HashValidator
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `pkg` stanza.
+    #
+    # @api private
     class Pkg < AbstractArtifact
       attr_reader :pkg_relative_path, :path, :stanza_options
 

Library/Homebrew/cask/artifact/postflight_block.rb

@@ -4,6 +4,9 @@ require "cask/artifact/abstract_flight_block"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `postflight` stanza.
+    #
+    # @api private
     class PostflightBlock < AbstractFlightBlock
     end
   end

Library/Homebrew/cask/artifact/preflight_block.rb

@@ -4,6 +4,9 @@ require "cask/artifact/abstract_flight_block"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `preflight` stanza.
+    #
+    # @api private
     class PreflightBlock < AbstractFlightBlock
     end
   end

Library/Homebrew/cask/artifact/prefpane.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `prefpane` stanza.
+    #
+    # @api private
     class Prefpane < Moved
       def self.english_name
         "Preference Pane"

Library/Homebrew/cask/artifact/qlplugin.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `qlplugin` stanza.
+    #
+    # @api private
     class Qlplugin < Moved
       def self.english_name
         "QuickLook Plugin"

Library/Homebrew/cask/artifact/relocated.rb

@@ -7,6 +7,9 @@ using HashValidator
 
 module Cask
   module Artifact
+    # Superclass for all artifacts which have a source and a target location.
+    #
+    # @api private
     class Relocated < AbstractArtifact
       def self.from_args(cask, *args)
         source_string, target_hash = args

Library/Homebrew/cask/artifact/screen_saver.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `screen_saver` stanza.
+    #
+    # @api private
     class ScreenSaver < Moved
     end
   end

Library/Homebrew/cask/artifact/service.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `service` stanza.
+    #
+    # @api private
     class Service < Moved
     end
   end

Library/Homebrew/cask/artifact/stage_only.rb

@@ -4,6 +4,9 @@ require "cask/artifact/abstract_artifact"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `stage_only` stanza.
+    #
+    # @api private
     class StageOnly < AbstractArtifact
       def self.from_args(cask, *args)
         raise CaskInvalidError.new(cask.token, "'stage_only' takes only a single argument: true") if args != [true]

Library/Homebrew/cask/artifact/suite.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `suite` stanza.
+    #
+    # @api private
     class Suite < Moved
       def self.english_name
         "App Suite"

Library/Homebrew/cask/artifact/symlinked.rb

@@ -4,6 +4,9 @@ require "cask/artifact/relocated"
 
 module Cask
   module Artifact
+    # Superclass for all artifacts which are installed by symlinking them to the target location.
+    #
+    # @api private
     class Symlinked < Relocated
       def self.link_type_english_name
         "Symlink"

Library/Homebrew/cask/artifact/uninstall.rb

@@ -4,6 +4,9 @@ require "cask/artifact/abstract_uninstall"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `uninstall` stanza.
+    #
+    # @api private
     class Uninstall < AbstractUninstall
       def uninstall_phase(**options)
         ORDERED_DIRECTIVES.reject { |directive_sym| directive_sym == :rmdir }

Library/Homebrew/cask/artifact/vst3_plugin.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `vst3_plugin` stanza.
+    #
+    # @api private
     class Vst3Plugin < Moved
     end
   end

Library/Homebrew/cask/artifact/vst_plugin.rb

@@ -4,6 +4,9 @@ require "cask/artifact/moved"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `vst_plugin` stanza.
+    #
+    # @api private
     class VstPlugin < Moved
     end
   end

Library/Homebrew/cask/artifact/zap.rb

@@ -4,6 +4,9 @@ require "cask/artifact/abstract_uninstall"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `zap` stanza.
+    #
+    # @api private
     class Zap < AbstractUninstall
       def zap_phase(**options)
         dispatch_uninstall_directives(**options)

Library/Homebrew/cask/audit.rb

@@ -8,6 +8,9 @@ require "utils/git"
 require "utils/notability"
 
 module Cask
+  # Audit a cask for various problems.
+  #
+  # @api private
   class Audit
     extend Predicable