Merge pull request #17165 from reitermarkus/docs-private-by-default

.github/ISSUE_TEMPLATE.md

@@ -1 +1 @@
-# Please fill out one of the templates on: https://github.com/Homebrew/brew/issues/new/choose or we will close it without comment.
+Please fill out one of the templates on https://github.com/Homebrew/brew/issues/new/choose or we will close your issue without comment.

.github/workflows/docs.yml

@@ -25,9 +25,22 @@ jobs:
       - name: Install vale
         run: brew install vale
 
-      - name: Run vale for docs linting
-        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}/docs
-        run: vale .
+      - name: Lint docs
+        working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}
+        run: |
+          set -euo pipefail
+
+          # Avoid failing on broken symlinks.
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/fuse.pc
+          rm Library/Homebrew/os/mac/pkgconfig/fuse/osxfuse.pc
+
+          # No ignore support (https://github.com/errata-ai/vale/issues/131).
+          rm -r Library/Homebrew/vendor
+
+          vale .
+
+          # Restore removed files.
+          git reset --hard
 
       - name: Install Ruby
         uses: ruby/setup-ruby@1198b074305f9356bd56dd4b311757cc0dab2f1c # v1.175.1

.gitignore

@@ -107,6 +107,7 @@
 **/vendor/bundle/ruby/*/gems/rainbow-*/
 **/vendor/bundle/ruby/*/gems/rbi-*/
 **/vendor/bundle/ruby/*/gems/rdoc-*/
+**/vendor/bundle/ruby/*/gems/redcarpet-*/
 **/vendor/bundle/ruby/*/gems/regexp_parser-*/
 **/vendor/bundle/ruby/*/gems/rexml-*/
 **/vendor/bundle/ruby/*/gems/rspec-*/

.vale.ini

@@ -1,4 +1,7 @@
 StylesPath = ./docs/vale-styles
 
-[*.md]
+[formats]
+rb = md
+
+[*.{md,rb}]
 BasedOnStyles = Homebrew

Library/Homebrew/.rubocop.yml

@@ -70,6 +70,11 @@ Style/Documentation:
     - version.rb
     - tap.rb
 
+Homebrew/NegateInclude:
+  Exclude:
+    # YARD runs stand-alone.
+    - yard/docstring_parser.rb
+
 Style/DocumentationMethod:
   Include:
     - "formula.rb"

Library/Homebrew/Gemfile

@@ -16,6 +16,7 @@ end
 # installed gems (should all be require: false)
 # ALL gems that are not vendored should be in a group
 group :doc, optional: true do
+  gem "redcarpet", require: false
   gem "yard", require: false
   gem "yard-sorbet", require: false
 end

Library/Homebrew/Gemfile.lock

@@ -53,6 +53,7 @@ GEM
     rbi (0.1.12)
       prism (>= 0.18.0, < 0.28)
       sorbet-runtime (>= 0.5.9204)
+    redcarpet (3.6.0)
     regexp_parser (2.9.0)
     rexml (3.2.6)
     rspec (3.13.0)
@@ -175,6 +176,7 @@ DEPENDENCIES
   patchelf
   plist
   pry
+  redcarpet
   rexml
   rspec
   rspec-github

Library/Homebrew/PATH.rb

@@ -60,7 +60,6 @@ def to_str
     @paths.join(File::PATH_SEPARATOR)
   end
 
-  # @!visibility private
   sig { returns(String) }
   def to_s = to_str
 

Library/Homebrew/abstract_command.rb

@@ -6,9 +6,10 @@
 module Homebrew
   # Subclass this to implement a `brew` command. This is preferred to declaring a named function in the `Homebrew`
   # module, because:
+  #
   # - Each Command lives in an isolated namespace.
   # - Each Command implements a defined interface.
-  # - `args` is available as an ivar, and thus does not need to be passed as an argument to helper methods.
+  # - `args` is available as an instance method and thus does not need to be passed as an argument to helper methods.
   # - Subclasses no longer need to reference `CLI::Parser` or parse args explicitly.
   #
   # To subclass, implement a `run` method and provide a `cmd_args` block to document the command and its allowed args.

Library/Homebrew/attestation.rb

@@ -39,8 +39,8 @@ class InvalidAttestationError < RuntimeError; end
     sig { returns(Pathname) }
     def self.gh_executable
       # NOTE: We disable HOMEBREW_VERIFY_ATTESTATIONS when installing `gh` itself,
-      # to prevent a cycle during bootstrapping. This can eventually be resolved
-      # by vendoring a pure-Ruby Sigstore verifier client.
+      #       to prevent a cycle during bootstrapping. This can eventually be resolved
+      #       by vendoring a pure-Ruby Sigstore verifier client.
       @gh_executable ||= T.let(with_env("HOMEBREW_VERIFY_ATTESTATIONS" => nil) do
         ensure_executable!("gh")
       end, T.nilable(Pathname))

Library/Homebrew/brew.sh

@@ -265,7 +265,7 @@ EOS
   fi
 }
 
-# NOTE: the members of the array in the second arg must not have spaces!
+# NOTE: The members of the array in the second arg must not have spaces!
 check-array-membership() {
   local item=$1
   shift

Library/Homebrew/brew_irbrc

@@ -1,6 +1,6 @@
-# Note: that we use a non-standard config file name to reduce
-# name clashes with other IRB config files like `.irbrc`.
-# Note #2: This doesn't work with system Ruby for some reason.
+# NOTE: We use a non-standard config file name to reduce name clashes with
+#       other IRB config files like `.irbrc`.
+# NOTE: This doesn't work with system Ruby for some reason.
 
 require 'irb/completion'
 

Library/Homebrew/build_environment.rb

@@ -28,7 +28,7 @@ def std?
   # DSL for specifying build environment settings.
   module DSL
     # Initialise @env for each class which may use this DSL (e.g. each formula subclass).
-    # `env` may never be called, and it needs to be initialised before the class is frozen.
+    # `env` may never be called and it needs to be initialised before the class is frozen.
     def inherited(child)
       super
       child.instance_eval do

Library/Homebrew/build_options.rb

@@ -9,16 +9,26 @@ def initialize(args, options)
   end
 
   # True if a {Formula} is being built with a specific option.
-  # <pre>args << "--i-want-spam" if build.with? "spam"
   #
+  # ### Examples
+  #
+  # ```ruby
+  # args << "--i-want-spam" if build.with? "spam"
+  # ```
+  #
+  # ```ruby
   # args << "--qt-gui" if build.with? "qt" # "--with-qt" ==> build.with? "qt"
+  # ```
+  #
+  # If a formula presents a user with a choice, but the choice must be fulfilled:
   #
-  # # If a formula presents a user with a choice, but the choice must be fulfilled:
+  # ```ruby
   # if build.with? "example2"
   #   args << "--with-example2"
   # else
   #   args << "--with-example1"
-  # end</pre>
+  # end
+  # ```
   def with?(val)
     option_names = val.respond_to?(:option_names) ? val.option_names : [val]
 
@@ -34,7 +44,12 @@ def with?(val)
   end
 
   # True if a {Formula} is being built without a specific option.
-  # <pre>args << "--no-spam-plz" if build.without? "spam"</pre>
+  #
+  # ### Example
+  #
+  # ```ruby
+  # args << "--no-spam-plz" if build.without? "spam"
+  # ```
   def without?(val)
     !with?(val)
   end
@@ -45,19 +60,33 @@ def bottle?
   end
 
   # True if a {Formula} is being built with {Formula.head} instead of {Formula.stable}.
-  # <pre>args << "--some-new-stuff" if build.head?</pre>
-  # <pre># If there are multiple conditional arguments use a block instead of lines.
+  #
+  # ### Examples
+  #
+  # ```ruby
+  # args << "--some-new-stuff" if build.head?
+  # ```
+  #
+  # If there are multiple conditional arguments use a block instead of lines.
+  #
+  # ```ruby
   # if build.head?
   #   args << "--i-want-pizza"
   #   args << "--and-a-cold-beer" if build.with? "cold-beer"
-  # end</pre>
+  # end
+  # ```
   def head?
     include? "HEAD"
   end
 
   # True if a {Formula} is being built with {Formula.stable} instead of {Formula.head}.
   # This is the default.
-  # <pre>args << "--some-beta" if build.head?</pre>
+  #
+  # ### Example
+  #
+  # ```ruby
+  # args << "--some-beta" if build.head?
+  # ```
   def stable?
     !head?
   end

Library/Homebrew/cask/artifact/abstract_artifact.rb

@@ -147,7 +147,6 @@ def config
         cask.config
       end
 
-      # @!visibility private
       sig { returns(String) }
       def to_s
         "#{summarize} (#{self.class.english_name})"

Library/Homebrew/cask/audit.rb

@@ -685,7 +685,7 @@ def audit_gitlab_prerelease_version
 
     sig { void }
     def audit_github_repository_archived
-      # Deprecated/disabled casks may have an archived repo.
+      # Deprecated/disabled casks may have an archived repository.
       return if cask.discontinued? || cask.deprecated? || cask.disabled?
 
       user, repo = get_repo_data(%r{https?://github\.com/([^/]+)/([^/]+)/?.*}) if online?
@@ -699,7 +699,7 @@ def audit_github_repository_archived
 
     sig { void }
     def audit_gitlab_repository_archived
-      # Deprecated/disabled casks may have an archived repo.
+      # Deprecated/disabled casks may have an archived repository.
       return if cask.discontinued? || cask.deprecated? || cask.disabled?
 
       user, repo = get_repo_data(%r{https?://gitlab\.com/([^/]+)/([^/]+)/?.*}) if online?

Library/Homebrew/cask/cask.rb

@@ -78,7 +78,8 @@ def initialize(token, sourcefile_path: nil, source: nil, tap: nil, loaded_from_a
       @allow_reassignment = allow_reassignment
       @loaded_from_api = loaded_from_api
       @loader = loader
-      # Sorbet has trouble with bound procs assigned to ivars: https://github.com/sorbet/sorbet/issues/6843
+      # Sorbet has trouble with bound procs assigned to instance variables:
+      # https://github.com/sorbet/sorbet/issues/6843
       instance_variable_set(:@block, block)
 
       @default_config = config || Config.new
@@ -323,11 +324,9 @@ def populate_from_api!(json_cask)
     end
 
     # @api public
-    # @!visibility private
     sig { returns(String) }
     def to_s = token
 
-    # @!visibility private
     sig { returns(String) }
     def inspect
       "#<Cask #{token}#{sourcefile_path&.to_s&.prepend(" ")}>"