Merge pull request #14818 from issyl0/rubocop-documentation

rubocop: Only enable `Style/Documentation` for `@api public` code

.github/workflows/tests.yml

@@ -46,6 +46,19 @@ jobs:
 
       - run: brew typecheck
 
+      - name: Check RuboCop filepaths
+        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/Library/Homebrew
+        run: |
+          public_apis=$(git grep -l "@api public" | wc -l | tr -d ' ')
+          rubocop_docs=$(yq '.Style/Documentation.Include' .rubocop.yml | wc -l | tr -d ' ')
+          if [[ public_apis -ne rubocop_docs ]]
+          then
+            echo "All public Homebrew APIs should be included in the Style/Documentation RuboCop."
+            echo "There were ${public_apis} '@api public' lines but ${rubocop_docs} filepaths for the 'Style/Documentation' RuboCop."
+            echo "Add or remove the filepaths from Library/Homebrew/.rubocop.yml as appropriate."
+            exit 1
+          fi
+
   tap-syntax:
     name: tap syntax
     needs: syntax

Library/.rubocop.yml

@@ -359,7 +359,7 @@ Style/DisableCopsWithinSourceCodeDirective:
     - "/**/{Formula,Casks}/**/*.rb"
     - "**/{Formula,Casks}/**/*.rb"
 
-# Don't enforce documentation in casks or formulae.
+# The files actually scanned in this cop are in `Library/Homebrew/.rubocop.yml`.
 Style/Documentation:
   Exclude:
     - "Taps/**/*"

Library/Homebrew/.rubocop.yml

@@ -17,27 +17,48 @@ Naming/PredicateName:
     - is_32_bit?
     - is_64_bit?
 
+# Only enforce documentation for public APIs.
+# Checked by the tests.yml syntax job
 Style/Documentation:
   AllowedConstants:
     - Homebrew
-  Exclude:
-    - "extend/**/*.rb"
-    - "test/**/*.rb"
-    - "cask/macos.rb"
-    - "cli/args.rb"
-    - "cli/parser.rb"
-    - "cmd/list.rb"
-    - "cmd/update-report.rb"
-    - "dev-cmd/irb.rb"
-    - "dev-cmd/pr-pull.rb"
-    - "keg_relocate.rb"
-    - "os/mac/keg.rb"
-    - "software_spec.rb"
-    - "utils.rb"
-    - "utils/fork.rb"
-    - "utils/git_repository.rb"
-    - "utils/popen.rb"
-    - "utils/shell.rb"
+  Include:
+    - cask/dsl.rb
+    - cask/dsl/version.rb
+    - cask/url.rb
+    - download_strategy.rb
+    - extend/kernel.rb
+    - formula.rb
+    - formula_assertions.rb
+    - formula_free_port.rb
+    - language/go.rb
+    - language/java.rb
+    - language/node.rb
+    - language/perl.rb
+    - language/python.rb
+    - livecheck/strategy/apache.rb
+    - livecheck/strategy/bitbucket.rb
+    - livecheck/strategy/cpan.rb
+    - livecheck/strategy/extract_plist.rb
+    - livecheck/strategy/git.rb
+    - livecheck/strategy/github_latest.rb
+    - livecheck/strategy/gnome.rb
+    - livecheck/strategy/gnu.rb
+    - livecheck/strategy/hackage.rb
+    - livecheck/strategy/json.rb
+    - livecheck/strategy/launchpad.rb
+    - livecheck/strategy/npm.rb
+    - livecheck/strategy/page_match.rb
+    - livecheck/strategy/pypi.rb
+    - livecheck/strategy/sourceforge.rb
+    - livecheck/strategy/sparkle.rb
+    - livecheck/strategy/xorg.rb
+    - os.rb
+    - resource.rb
+    - utils/inreplace.rb
+    - utils/shebang.rb
+    - utils/string_inreplace_extension.rb
+    - version.rb
 
 Style/HashAsLastArrayItem:
   Exclude:

Library/Homebrew/extend/kernel.rb

@@ -1,6 +1,8 @@
 # typed: false
 # frozen_string_literal: true
 
+# Contains shorthand Homebrew utility methods like `ohai`, `opoo`, `odisabled`.
+# TODO: move these out of `Kernel`.
 module Kernel
   extend T::Sig
 

Library/Homebrew/test/style_spec.rb

@@ -40,7 +40,7 @@ describe Homebrew::Style do
   describe ".check_style_and_print" do
     let(:dir) { mktmpdir }
 
-    it "returns false for conforming file with only audit-level violations" do
+    it "returns true (success) for conforming file with only audit-level violations" do
       # This file is known to use non-rocket hashes and other things that trigger audit,
       # but not regular, cop violations
       target_file = HOMEBREW_LIBRARY_PATH/"utils.rb"