language: add detected_<language>_shebang to public API

[cho-m]

---

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests (excluding integration tests) for your changes? Here's an example.
• Have you successfully run brew lgtm (style, typechecking and tests) with your changes locally?

---

• AI was used to generate or assist with generating this PR. Please specify below how you used AI to help you, and what steps you have taken to manually verify the changes.

---

These are used in Homebrew/core formulae, particularly Python method. Perl has a couple. PHP was added specifically to use in formulae.

I had thought these were transitively public API via module, e.g.

brew/Library/Homebrew/language/perl.rb

Lines 7 to 8 in 3aae2a3

	# @api public
	module Perl

However, YARD output shows it as private

• https://docs.brew.sh/rubydoc/Language/Perl/Shebang.html#detected_perl_shebang-class_method

[Copilot]

Pull request overview

This PR updates Homebrew’s Language::*::Shebang helpers so that the detected_<language>_shebang methods are marked as public API in generated YARD documentation (for use by external formulae like those in Homebrew/core).

Changes:

• Mark detected_python_shebang as @api public in Language::Python::Shebang.
• Mark detected_php_shebang as @api public in Language::PHP::Shebang.
• Mark detected_perl_shebang as @api public in Language::Perl::Shebang.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
Library/Homebrew/language/python.rb	Adds # @api public to document detected_python_shebang as public API.
Library/Homebrew/language/php.rb	Adds # @api public to document detected_php_shebang as public API.
Library/Homebrew/language/perl.rb	Adds # @api public to document detected_perl_shebang as public API.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[MikeMcQuaid]

Should this be @api internal or is it already used widely outside the Homebrew organisation?

[ZhongRuoyu]

If this should be public API, should it also have a documenting comment? Something like:

Suggested change

	# @api public
	# Returns a {Utils::Shebang::RewriteInfo} object that contains necessary information for
	# rewriting a Python shebang to use the formula's Python dependency, or the `python3`
	# executable from `PATH` if `use_python_from_path` is `true`.
	#
	# To be used with {Utils::Shebang.rewrite_shebang}.
	#
	# @api public

Same for the other methods.

[cho-m]

Should this be @api internal or is it already used widely outside the Homebrew organisation?

For formulae usage, we've usually erred on @api public due to brew extract.

Python methods are going to be the most commonly used externally. It's used in places like homebrew-bio so that's years of usage by prior Homebrew maintainers.

• https://github.com/search?q=repo%3Abrewsci%2Fhomebrew-bio%20detected_python_shebang&type=code
• brewsci/homebrew-bio@494fdfd

We aren't likely to remove these, but in case we do then want to provide an odeprecate period.

[MikeMcQuaid]

Python methods are going to be the most commonly used externally. It's used in places like homebrew-bio so that's years of usage by prior Homebrew maintainers.

Cool, public seems fine then (provided there's docs).

For formulae usage, we've usually erred on @api public due to brew extract.

We should definitely not do that. Public APIs are a massive pain for us to deprecate. We should default to internal or private when we can.

[cho-m]

We should definitely not do that. Public APIs are a massive pain for us to deprecate. We should default to internal or private when we can.

For Homebrew/core, the problem is how easy it propagates outside of Homebrew org once we use it in a formula.

Personally would want to audit formulae so they can never use private/internal API and remove/replace any methods in existing formulae that we don't want exposed. However, not sure if it is possible to check against @api scope.

In rare cases, where we have no choice, would be nice to make internal API usage obvious (as an audit exception or explicit comment).

[MikeMcQuaid]

For Homebrew/core, the problem is how easy it propagates outside of Homebrew org once we use it in a formula.

Most formulae are not being brew extractd.

Personally would want to audit formulae so they can never use private/internal API

This defeats the point of having an internal API, no?

[cho-m]

This defeats the point of having an internal API, no?

Pre-repo merge, I would have considered internal API stuff we used in test-bot, bundle, extra commands, etc.

Now is a bit more vague as most code is within Homebrew/brew. At least would cover "cmds" included in Homebrew/core and Homebrew/cask.

Worth discussing what extent each scope should now cover.

---

Cask is a bit simpler as we have DSL layer so that should be public API. Flight blocks are the only problem as they can run arbitrary Ruby. I would consider stuff like set_ownership and set_permissions public API as those are historically used DSL and would cause external breakage if removed without odeprecate:

• https://docs.brew.sh/rubydoc/Cask/Staged.html#set_permissions-instance_method

Formulae is trickier as we are directly using Ruby subclass so very easy to bleed @api private methods. If we want to consider @api internal as acceptable then that does mean we permit more breaking changes.

[Bo98]

I would consider stuff like set_ownership and set_permissions public API as those are historically used DSL and would cause external breakage if removed without odeprecate

Those are indeed supposed to be public - they're listed in the cookbook.

It's probaly worth doing a pass through the annotations as a bunch of them don't seem to be accurate. The cookbook is probably a good start for a list of things that are definitely public.

Realistically very few people read rubydoc.brew.sh but many do read the cookbook as well as Homebrew/core formulae for examples (as the cookbook recommends in places - including as far as recommending grep-ing over Homebrew/core).

[MikeMcQuaid]

Might be good to at some point have a rubocop that checks for the inconsistencies between @public, Formula Cookbook and homebrew/core usage.

[MikeMcQuaid]

Might be good to at some point have a rubocop that checks for the inconsistencies between @public, Formula Cookbook and homebrew/core usage.

#21993