From 832bd8af2dd9279b0fcfee5a25ee38e921aa1a90 Mon Sep 17 00:00:00 2001
From: Issy Long <me@issyl0.co.uk>
Date: Sun, 26 Feb 2023 13:20:08 +0000
Subject: [PATCH] rubocop: Only enable `Style/Documentation` for `@api public`
 code

- Suggested in https://github.com/Homebrew/brew/pull/14709#issuecomment-1437461642.
- Found the public API paths with `git grep -l "@api public"`.
---
 Library/.rubocop.yml          | 46 ++++++++++++++++++++++++++++++-----
 Library/Homebrew/.rubocop.yml | 22 -----------------
 2 files changed, 40 insertions(+), 28 deletions(-)

diff --git a/Library/.rubocop.yml b/Library/.rubocop.yml
index 2a5c7350fa2e6e..5f0e737be401a9 100644
--- a/Library/.rubocop.yml
+++ b/Library/.rubocop.yml
@@ -339,13 +339,47 @@ Style/DisableCopsWithinSourceCodeDirective:
     - "/**/{Formula,Casks}/*.rb"
     - "**/{Formula,Casks}/*.rb"
 
-# Don't enforce documentation in casks or formulae.
+# Only enforce documentation for public APIs.
 Style/Documentation:
-  Exclude:
-    - "Taps/**/*"
-    - "/**/{Formula,Casks}/*.rb"
-    - "**/{Formula,Casks}/*.rb"
-    - "**/*.rbi"
+  AllowedConstants:
+    - Homebrew
+  Include:
+    - Homebrew/cask/dsl.rb
+    - Homebrew/cask/dsl/version.rb
+    - Homebrew/cask/url.rb
+    - Homebrew/download_strategy.rb
+    - Homebrew/formula.rb
+    - Homebrew/formula_assertions.rb
+    - Homebrew/formula_free_port.rb
+    - Homebrew/language/go.rb
+    - Homebrew/language/java.rb
+    - Homebrew/language/node.rb
+    - Homebrew/language/perl.rb
+    - Homebrew/language/python.rb
+    - Homebrew/livecheck/strategy/apache.rb
+    - Homebrew/livecheck/strategy/bitbucket.rb
+    - Homebrew/livecheck/strategy/cpan.rb
+    - Homebrew/livecheck/strategy/extract_plist.rb
+    - Homebrew/livecheck/strategy/git.rb
+    - Homebrew/livecheck/strategy/github_latest.rb
+    - Homebrew/livecheck/strategy/gnome.rb
+    - Homebrew/livecheck/strategy/gnu.rb
+    - Homebrew/livecheck/strategy/hackage.rb
+    - Homebrew/livecheck/strategy/json.rb
+    - Homebrew/livecheck/strategy/launchpad.rb
+    - Homebrew/livecheck/strategy/npm.rb
+    - Homebrew/livecheck/strategy/page_match.rb
+    - Homebrew/livecheck/strategy/pypi.rb
+    - Homebrew/livecheck/strategy/sourceforge.rb
+    - Homebrew/livecheck/strategy/sparkle.rb
+    - Homebrew/livecheck/strategy/xorg.rb
+    - Homebrew/os.rb
+    - Homebrew/resource.rb
+    - Homebrew/utils.rb
+    - Homebrew/utils/inreplace.rb
+    - Homebrew/utils/shebang.rb
+    - Homebrew/utils/string_inreplace_extension.rb
+    - Homebrew/version.rb
 
 Style/DocumentationMethod:
   Include:
diff --git a/Library/Homebrew/.rubocop.yml b/Library/Homebrew/.rubocop.yml
index 8f3c4b34a15e42..a72e17bf6690b1 100644
--- a/Library/Homebrew/.rubocop.yml
+++ b/Library/Homebrew/.rubocop.yml
@@ -17,28 +17,6 @@ Naming/PredicateName:
     - is_32_bit?
     - is_64_bit?
 
-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"
-
 Style/HashAsLastArrayItem:
   Exclude:
     - "test/utils/spdx_spec.rb"