Merge pull request #8339 from reitermarkus/documentation

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

Library/.rubocop_cask.yml

@@ -27,5 +27,9 @@ Cask/StanzaOrder:
 # don't want these for casks but re-enabled for Library/Homebrew
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
 Metrics/BlockLength:
   Enabled: false

Library/Homebrew/.rubocop.yml

-inherit_from: ../.rubocop_rspec.yml
+inherit_from:
+  - ../.rubocop_rspec.yml
+  - .rubocop_todo.yml
 
 AllCops:
   Include:
@@ -105,12 +107,6 @@ Naming/MethodParameterName:
 Style/AccessModifierDeclarations:
   Enabled: false
 
-# make rspec formatting more flexible
-Style/BlockDelimiters:
-  Exclude:
-    - '**/*_spec.rb'
-    - '**/shared_examples/**/*.rb'
-
 # don't group nicely documented or private attr_readers
 Style/AccessorGrouping:
   Exclude:
@@ -121,11 +117,16 @@ Style/AccessorGrouping:
     - 'system_command.rb'
     - 'tap.rb'
 
+# make rspec formatting more flexible
+Style/BlockDelimiters:
+  Exclude:
+    - '**/*_spec.rb'
+    - '**/shared_examples/**/*.rb'
+
 # document our public APIs
 Style/Documentation:
   Enabled: true
-  Include:
-    - 'formula.rb'
+
 Style/DocumentationMethod:
   Enabled: true
   Include:

Library/Homebrew/.rubocop_todo.yml

+Style/Documentation:
+  Exclude:
+    - 'compat/**/*.rb'
+    - 'extend/**/*.rb'
+    - 'cmd/**/*.rb'
+    - 'dev-cmd/**/*.rb'
+    - 'test/**/*.rb'
+    - 'cask/macos.rb'
+    - 'cli/args.rb'
+    - 'cli/parser.rb'
+    - 'download_strategy.rb'
+    - 'global.rb'
+    - 'keg_relocate.rb'
+    - 'os/linux/global.rb'
+    - 'os/mac/architecture_list.rb'
+    - 'os/mac/keg.rb'
+    - 'reinstall.rb'
+    - 'software_spec.rb'
+    - 'upgrade.rb'
+    - 'utils.rb'
+    - 'utils/fork.rb'
+    - 'utils/gems.rb'
+    - 'utils/notability.rb'
+    - 'utils/popen.rb'
+    - 'utils/pypi.rb'
+    - 'utils/shebang.rb'
+    - 'utils/shell.rb'
+    - 'utils/spdx.rb'
+    - 'utils/livecheck_formula.rb'
+    - 'utils/repology.rb'
+    - 'version.rb'

Library/Homebrew/PATH.rb

 # frozen_string_literal: true
 
+# Represention of a `*PATH` environment variable.
+#
+# @api private
 class PATH
   include Enumerable
   extend Forwardable

Library/Homebrew/bintray.rb

@@ -3,6 +3,9 @@
 require "utils/curl"
 require "json"
 
+# Bintray API client.
+#
+# @api private
 class Bintray
   include Context
 

Library/Homebrew/build.rb

@@ -15,6 +15,9 @@ require "fcntl"
 require "socket"
 require "cmd/install"
 
+# A formula build.
+#
+# @api private
 class Build
   attr_reader :formula, :deps, :reqs, :args
 

Library/Homebrew/build_options.rb

 # frozen_string_literal: true
 
+# Options for a formula build.
+#
+# @api private
 class BuildOptions
   # @private
   def initialize(args, options)

Library/Homebrew/cask/artifact.rb

@@ -27,6 +27,9 @@ require "cask/artifact/uninstall"
 require "cask/artifact/zap"
 
 module Cask
+  # Module containing all cask artifact classes.
+  #
+  # @api private
   module Artifact
   end
 end

Library/Homebrew/cask/artifact/abstract_artifact.rb

@@ -2,6 +2,9 @@
 
 module Cask
   module Artifact
+    # Abstract superclass for all artifacts.
+    #
+    # @api private
     class AbstractArtifact
       include Comparable
       extend Predicable

Library/Homebrew/cask/artifact/abstract_flight_block.rb

@@ -4,6 +4,9 @@ require "cask/artifact/abstract_artifact"
 
 module Cask
   module Artifact
+    # Abstract superclass for block artifacts.
+    #
+    # @api private
     class AbstractFlightBlock < AbstractArtifact
       def self.dsl_key
         super.to_s.sub(/_block$/, "").to_sym

Library/Homebrew/cask/artifact/abstract_uninstall.rb

@@ -10,6 +10,9 @@ using HashValidator
 
 module Cask
   module Artifact
+    # Abstract superclass for uninstall artifacts.
+    #
+    # @api private
     class AbstractUninstall < AbstractArtifact
       ORDERED_DIRECTIVES = [
         :early_script,

Library/Homebrew/cask/artifact/app.rb

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

Library/Homebrew/cask/artifact/artifact.rb

@@ -7,6 +7,9 @@ using HashValidator
 
 module Cask
   module Artifact
+    # Generic artifact corresponding to the `artifact` stanza.
+    #
+    # @api private
     class Artifact < Moved
       def self.english_name
         "Generic Artifact"

Library/Homebrew/cask/artifact/audio_unit_plugin.rb

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

Library/Homebrew/cask/artifact/binary.rb

@@ -4,6 +4,9 @@ require "cask/artifact/symlinked"
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `binary` stanza.
+    #
+    # @api private
     class Binary < Symlinked
       def link(command: nil, **options)
         super(command: command, **options)

Library/Homebrew/cask/artifact/colorpicker.rb

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

Library/Homebrew/cask/artifact/dictionary.rb

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

Library/Homebrew/cask/artifact/font.rb

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

Library/Homebrew/cask/artifact/input_method.rb

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

Library/Homebrew/cask/artifact/installer.rb

@@ -7,12 +7,16 @@ using HashValidator
 
 module Cask
   module Artifact
+    # Artifact corresponding to the `installer` stanza.
+    #
+    # @api private
     class Installer < AbstractArtifact
       VALID_KEYS = Set.new([
                              :manual,
                              :script,
                            ]).freeze
 
+      # Extension module for manual installers.
       module ManualInstaller
         def install_phase(**)
           puts <<~EOS
@@ -23,6 +27,7 @@ module Cask
         end
       end
 
+      # Extension module for script installers.
       module ScriptInstaller
         def install_phase(command: nil, **_)
           ohai "Running #{self.class.dsl_key} script '#{path}'"