Merge pull request #8492 from reitermarkus/document-shebang

Document `Shebang`.

Library/Homebrew/.rubocop_todo.yml

@@ -22,7 +22,6 @@ Style/Documentation:
     - 'utils/gems.rb'
     - 'utils/notability.rb'
     - 'utils/popen.rb'
-    - 'utils/shebang.rb'
     - 'utils/shell.rb'
     - 'utils/livecheck_formula.rb'
     - 'version.rb'

Library/Homebrew/utils/shebang.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
 module Utils
+  # Helper functions for manipulating shebang lines.
+  #
+  # @api private
   module Shebang
     module_function
 
+    # Specification on how to rewrite a given shebang.
+    #
+    # @api private
     class RewriteInfo
       attr_reader :regex, :max_length, :replacement
 
@@ -14,6 +20,12 @@ module Utils
       end
     end
 
+    # Rewrite shebang for the given `paths` using the given `rewrite_info`.
+    #
+    # @example
+    #   rewrite_shebang detected_python_shebang, bin/"script.py"
+    #
+    # @api public
     def rewrite_shebang(rewrite_info, *paths)
       paths.each do |f|
         f = Pathname(f)