asdfasdfasdf

Library/Homebrew/cask/dsl.rb

@@ -112,6 +112,16 @@ def initialize(cask)
       @token = cask.token
     end
 
+    # Specifies the cask's name.
+    #
+    # NOTE: Multiple names can be specified.
+    #
+    # ### Example
+    #
+    # ```ruby
+    # name "Visual Studio Code"
+    # ```
+    #
     # @api public
     def name(*args)
       @name ||= []
@@ -120,6 +130,14 @@ def name(*args)
       @name.concat(args.flatten)
     end
 
+    # Describes the cask.
+    #
+    # ### Example
+    #
+    # ```ruby
+    # desc "Open-source code editor"
+    # ```
+    #
     # @api public
     def desc(description = nil)
       set_unique_stanza(:desc, description.nil?) { description }
@@ -146,6 +164,14 @@ def set_unique_stanza(stanza, should_return)
       raise CaskInvalidError.new(cask, "'#{stanza}' stanza failed with: #{e}")
     end
 
+    # Sets the cask's homepage.
+    #
+    # ### Example
+    #
+    # ```ruby
+    # homepage "https://code.visualstudio.com/"
+    # ```
+    #
     # @api public
     def homepage(homepage = nil)
       set_unique_stanza(:homepage, homepage.nil?) { homepage }
@@ -201,6 +227,14 @@ def languages
       @language_blocks.keys.flatten
     end
 
+    # Sets the cask's download URL.
+    #
+    # ### Example
+    #
+    # ```ruby
+    # url "https://update.code.visualstudio.com/#{version}/#{arch}/stable"
+    # ```
+    #
     # @api public
     def url(*args, **options, &block)
       caller_location = T.must(caller_locations).fetch(0)
@@ -214,6 +248,8 @@ def url(*args, **options, &block)
       end
     end
 
+    # Sets the cask's appcast URL.
+    #
     # @api public
     def appcast(*args, **kwargs)
       set_unique_stanza(:appcast, args.empty? && kwargs.empty?) do
@@ -222,13 +258,38 @@ def appcast(*args, **kwargs)
       end
     end
 
+    # Sets the cask's container type or nested container path.
+    #
+    # ### Examples
+    #
+    # The container is a nested disk image:
+    #
+    # ```ruby
+    # container nested: "orca-#{version}.dmg"
+    # ```
+    #
+    # The container should not be unarchived:
+    #
+    # ```ruby
+    # container type: :naked
+    # ```
+    #
     # @api public
     def container(**kwargs)
       set_unique_stanza(:container, kwargs.empty?) do
         DSL::Container.new(**kwargs)
       end
     end
 
+    # Sets the cask's version.
+    #
+    # ### Example
+    #
+    # ```ruby
+    # version "1.88.1"
+    # ```
+    #
+    # @see DSL::Version
     # @api public
     def version(arg = nil)
       set_unique_stanza(:version, arg.nil?) do
@@ -240,6 +301,23 @@ def version(arg = nil)
       end
     end
 
+    # Sets the cask's download checksum.
+    #
+    # ### Example
+    #
+    # For universal or single-architecture downloads:
+    #
+    # ```ruby
+    # sha256 "7bdb497080ffafdfd8cc94d8c62b004af1be9599e865e5555e456e2681e150ca"
+    # ```
+    #
+    # For architecture-dependent downloads:
+    #
+    # ```ruby
+    # sha256 arm:   "7bdb497080ffafdfd8cc94d8c62b004af1be9599e865e5555e456e2681e150ca",
+    #         intel: "b3c1c2442480a0219b9e05cf91d03385858c20f04b764ec08a3fa83d1b27e7b2"
+    # ```
+    #
     # @api public
     def sha256(arg = nil, arm: nil, intel: nil)
       should_return = arg.nil? && arm.nil? && intel.nil?
@@ -259,6 +337,14 @@ def sha256(arg = nil, arm: nil, intel: nil)
       end
     end
 
+    # Sets the cask's archtecture strings.
+    #
+    # ### Example
+    #
+    # ```ruby
+    # arch arm: "darwin-arm64", intel: "darwin"
+    # ```
+    #
     # @api public
     def arch(arm: nil, intel: nil)
       should_return = arm.nil? && intel.nil?

Library/Homebrew/cask/url.rb

@@ -87,7 +87,7 @@ module PageWithURL
       sig {
         params(
           uri:   T.nilable(T.any(URI::Generic, String)),
-          dsl:   T.nilable(::Cask::DSL),
+          dsl:   ::Cask::DSL,
           block: T.proc.params(arg0: T.all(String, PageWithURL))
                        .returns(T.any(T.any(URI::Generic, String), [T.any(URI::Generic, String), Hash])),
         ).void
@@ -114,6 +114,8 @@ def call
         end
       end
 
+      # Allows calling a nested `url` stanza in a `url do` block.
+      #
       # @api public
       sig {
         params(
@@ -123,10 +125,12 @@ def call
         ).returns(T.any(T.any(URI::Generic, String), [T.any(URI::Generic, String), Hash]))
       }
       def url(uri, &block)
-        self.class.new(uri, &block).call
+        self.class.new(uri, dsl: @dsl, &block).call
       end
       private :url
 
+      # This allows calling DSL methods from inside a `url` block.
+      #
       # @api public
       def method_missing(method, *args, &block)
         if @dsl.respond_to?(method)
@@ -135,10 +139,12 @@ def method_missing(method, *args, &block)
           super
         end
       end
+      private :method_missing
 
       def respond_to_missing?(method, include_all)
         @dsl.respond_to?(method, include_all) || super
       end
+      private :respond_to_missing?
     end
 
     sig {
@@ -187,7 +193,7 @@ def initialize(
       super(
         if block
           LazyObject.new do
-            uri2, options = *BlockDSL.new(uri, dsl:, &block).call
+            uri2, options = *BlockDSL.new(uri, dsl: T.must(dsl), &block).call
             options ||= {}
             DSL.new(uri2, **options)
           end

Library/Homebrew/rubocops/safe_navigation_with_blank.rb

@@ -9,9 +9,7 @@ module Homebrew
       #
       # NOTE: While the safe navigation operator is generally a good idea, when
       #       checking `foo&.blank?` in a conditional, `foo` being `nil` will actually
-      #       do the opposite of what the author intends.
-      #
-      #       For example:
+      #       do the opposite of what the author intends:
       #
       #       ```ruby
       #       foo&.blank? #=> nil

Library/Homebrew/yard/docstring_parser.rb

@@ -59,8 +59,6 @@ def parse_content(content)
             end
 
             tags << create_tag("deprecated", description)
-          else
-            log.error "Not deprecating #{object}."
           end
         end