` is
+ # Print some important notice to the user when `brew info [formula]` is
# called or when brewing a formula.
# This is optional. You can use all the vars like #{version} here.
# EOS
@@ -1040,8 +1041,8 @@ class Formula
nil
end
- # rarely, you don't want your library symlinked into the main prefix
- # see gettext.rb for an example
+ # Rarely, you don't want your library symlinked into the main prefix.
+ # See `gettext.rb` for an example.
def keg_only?
return false unless keg_only_reason
@@ -1319,7 +1320,7 @@ class Formula
end
# Standard parameters for CMake builds.
- # Setting CMAKE_FIND_FRAMEWORK to "LAST" tells CMake to search for our
+ # Setting `CMAKE_FIND_FRAMEWORK` to "LAST" tells CMake to search for our
# libraries before trying to utilize Frameworks, many of which will be from
# 3rd party installs.
# Note: there isn't a std_autotools variant because autotools is a lot
@@ -1951,7 +1952,7 @@ class Formula
end
# Create a temporary directory then yield. When the block returns,
- # recursively delete the temporary directory. Passing opts[:retain]
+ # recursively delete the temporary directory. Passing `opts[:retain]`
# or calling `do |staging| ... staging.retain!` in the block will skip
# the deletion and retain the temporary directory's contents.
def mktemp(prefix = name, opts = {})
@@ -2159,10 +2160,10 @@ class Formula
attr_rw :revision
# @!attribute [w] version_scheme
- # Used for creating new Homebrew versions schemes. For example, if we want
+ # Used for creating new Homebrew version schemes. For example, if we want
# to change version scheme from one to another, then we may need to update
# `version_scheme` of this {Formula} to be able to use new version scheme.
- # E.g. to move from 20151020 scheme to 1.0.0 we need to increment
+ # e.g. to move from 20151020 scheme to 1.0.0 we need to increment
# `version_scheme`. Without this, the prior scheme will always equate to a
# higher version.
# `0` if unset.
@@ -2177,14 +2178,15 @@ class Formula
end
# @!attribute [w] url
- # The URL used to download the source for the {#stable} version of the formula.
+ # The URL used to download the source for the {.stable} version of the formula.
# We prefer `https` for security and proxy reasons.
# If not inferrable, specify the download strategy with `:using => ...`
- # `:git`, `:hg`, `:svn`, `:bzr`, `:cvs`,
- # `:curl` (normal file download. Will also extract.)
- # `:nounzip` (without extracting)
- # `:post` (download via an HTTP POST)
- # `:s3` (download from S3 using signed request)
+ #
+ # - `:git`, `:hg`, `:svn`, `:bzr`, `:fossil`, `:cvs`,
+ # - `:curl` (normal file download. Will also extract.)
+ # - `:nounzip` (without extracting)
+ # - `:post` (download via an HTTP POST)
+ # - `:s3` (download from S3 using signed request)
#
# url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"
# url "https://some.dont.provide.archives.example.com",
@@ -2196,7 +2198,7 @@ class Formula
end
# @!attribute [w] version
- # The version string for the {#stable} version of the formula.
+ # The version string for the {.stable} version of the formula.
# The version is autodetected from the URL and/or tag so only needs to be
# declared if it cannot be autodetected correctly.
#
@@ -2206,7 +2208,7 @@ class Formula
end
# @!attribute [w] mirror
- # Additional URLs for the {#stable} version of the formula.
+ # Additional URLs for the {.stable} version of the formula.
# These are only used if the {.url} fails to download. It's optional and
# there can be more than one. Generally we add them when the main {.url}
# is unreliable. If {.url} is really unreliable then we may swap the
@@ -2220,8 +2222,8 @@ class Formula
# @!attribute [w] sha256
# @scope class
- # To verify the {#cached_download}'s integrity and security we verify the
- # SHA-256 hash matches what we've declared in the {Formula}. To quickly fill
+ # To verify the cached download's integrity and security we verify the
+ # SHA-256 hash matches which we've declared in the {Formula}. To quickly fill
# this value you can leave it blank and run `brew fetch --force` and it'll
# tell you the currently valid value.
#
@@ -2237,7 +2239,7 @@ class Formula
# and you haven't passed or previously used any options on this formula.
#
# If you maintain your own repository, you can add your own bottle links.
- # https://docs.brew.sh/Bottles
+ # @see https://docs.brew.sh/Bottles
# You can ignore this block entirely if submitting to Homebrew/homebrew-core.
# It'll be handled for you by the Brew Test Bot.
#
@@ -2251,11 +2253,11 @@ class Formula
# sha256 "1121cfccd5913f0a63fec40a6ffd44ea64f9dc135c66634ba001d10bcf4302a2" => :mavericks
# end
#
- # Only formulae where the upstream URL breaks or moves frequently, require compile
+ # Only formulae where the upstream URL breaks or moves frequently, require compiling
# or have a reasonable amount of patches/resources should be bottled.
# Formulae which do not meet the above requirements should not be bottled.
#
- # Formulae which should not be bottled & can be installed without any compile
+ # Formulae which should not be bottled and can be installed without any compile
# required should be tagged with:
# bottle :unneeded
#
@@ -2272,7 +2274,7 @@ class Formula
end
# @!attribute [w] stable
- # Allows adding {.depends_on} and {#patch}es just to the {.stable} {SoftwareSpec}.
+ # Allows adding {.depends_on} and {Patch}es just to the {.stable} {SoftwareSpec}.
# This is required instead of using a conditional.
# It is preferrable to also pull the {url} and {.sha256} into the block if one is added.
#
@@ -2314,7 +2316,7 @@ class Formula
# This can be installed by passing the `--HEAD` option to allow
# installing software directly from a branch of a version-control repository.
# If called as a method this provides just the {url} for the {SoftwareSpec}.
- # If a block is provided you can also add {.depends_on} and {#patch}es just to the {.head} {SoftwareSpec}.
+ # If a block is provided you can also add {.depends_on} and {Patch}es just to the {.head} {SoftwareSpec}.
# The download strategies (e.g. `:using =>`) are the same as for {url}.
# `master` is the default branch and doesn't need stating with a `:branch` parameter.
# head "https://we.prefer.https.over.git.example.com/.git"
@@ -2333,8 +2335,8 @@ class Formula
end
# Additional downloads can be defined as resources and accessed in the
- # install method. Resources can also be defined inside a stable, devel, or
- # head block. This mechanism replaces ad-hoc "subformula" classes.
+ # install method. Resources can also be defined inside a {.stable}, {.devel} or
+ # {.head} block. This mechanism replaces ad-hoc "subformula" classes.
# resource "additional_files" do
# url "https://example.com/additional-stuff.tar.gz"
# sha256 "c6bc3f48ce8e797854c4b865f6a8ff969867bbcaebd648ae6fd825683e59fef2"
@@ -2378,11 +2380,10 @@ class Formula
# depends_on :ld64 # Sometimes ld fails on `MacOS.version < :leopard`. Then use this.
# depends_on :x11 => :optional # X11/XQuartz components.
# depends_on :osxfuse # Permits the use of the upstream signed binary or our source package.
- # depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.
+ # depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.
# # It is possible to only depend on something if
# # `build.with?` or `build.without? "another_formula"`:
- # depends_on "postgresql" if build.without? "sqlite"
- #
+ # depends_on "postgresql" if build.without? "sqlite"
# # Python 3.x if the `--with-python` is given to `brew install example`
# depends_on "python3" => :optional
# # Python 2.7:
@@ -2397,10 +2398,11 @@ class Formula
# Options can be used as arguments to `brew install`.
# To switch features on/off: `"with-something"` or `"with-otherthing"`.
# To use other software: `"with-other-software"` or `"without-foo"`
- # Note, that for {.depends_on} that are `:optional` or `:recommended`, options
+ # Note that for {.depends_on} that are `:optional` or `:recommended`, options
# are generated automatically.
#
# There are also some special options:
+ #
# - `:universal`: build a universal binary/library (e.g. on newer Intel Macs
# this means a combined x86_64/x86 binary/library).
# option "with-spam", "The description goes here without a dot at the end"
@@ -2491,10 +2493,10 @@ class Formula
@skip_clean_paths ||= Set.new
end
- # Software that will not be sym-linked into the `brew --prefix` will only
+ # Software that will not be symlinked into the `brew --prefix` will only
# live in its Cellar. Other formulae can depend on it and then brew will
# add the necessary includes and libs (etc.) during the brewing of that
- # other formula. But generally, keg_only formulae are not in your PATH
+ # other formula. But generally, keg-only formulae are not in your PATH
# and not seen by compilers if you build your own software outside of
# Homebrew. This way, we don't shadow software provided by macOS.
# keg_only :provided_by_macos
@@ -2503,7 +2505,7 @@ class Formula
@keg_only_reason = KegOnlyReason.new(reason, explanation)
end
- # Pass :skip to this method to disable post-install stdlib checking
+ # Pass `:skip` to this method to disable post-install stdlib checking
def cxxstdlib_check(check_type)
define_method(:skip_cxxstdlib_check?) { true } if check_type == :skip
end
@@ -2538,13 +2540,13 @@ class Formula
specs.each { |spec| spec.needs(*standards) }
end
- # Test (is required for new formula and makes us happy).
+ # A test is required for new formulae and makes us happy.
# @return [Boolean]
#
# The block will create, run in and delete a temporary directory.
#
# We are fine if the executable does not error out, so we know linking
- # and building the software was ok.
+ # and building the software was OK.
# system bin/"foobar", "--version"
#
# (testpath/"test.file").write <<~EOS
diff --git a/Library/Homebrew/formula_support.rb b/Library/Homebrew/formula_support.rb
index fcdd45630f..05347a10d1 100644
--- a/Library/Homebrew/formula_support.rb
+++ b/Library/Homebrew/formula_support.rb
@@ -1,4 +1,4 @@
-# Used to track formulae that cannot be installed at the same time
+# Used to track formulae that cannot be installed at the same time.
FormulaConflict = Struct.new(:name, :reason)
# Used to annotate formulae that duplicate macOS provided software
@@ -39,7 +39,7 @@ class KegOnlyReason
end
end
-# Used to annotate formulae that don't require compiling or cannot build bottle.
+# Used to annotate formulae that don't require compiling or cannot build a bottle.
class BottleDisableReason
SUPPORTED_TYPES = [:unneeded, :disable].freeze
diff --git a/Library/Homebrew/formulary.rb b/Library/Homebrew/formulary.rb
index 044f8e242e..44f40685fa 100644
--- a/Library/Homebrew/formulary.rb
+++ b/Library/Homebrew/formulary.rb
@@ -1,7 +1,7 @@
require "digest/md5"
require "extend/cachable"
-# The Formulary is responsible for creating instances of Formula.
+# The Formulary is responsible for creating instances of {Formula}.
# It is not meant to be used directly from formulae.
module Formulary
@@ -175,7 +175,7 @@ module Formulary
end
end
- # Loads formulae from disk using a path
+ # Loads formulae from disk using a path.
class FromPathLoader < FormulaLoader
def initialize(path)
path = Pathname.new(path).expand_path
@@ -183,7 +183,7 @@ module Formulary
end
end
- # Loads formulae from URLs
+ # Loads formulae from URLs.
class FromUrlLoader < FormulaLoader
attr_reader :url
@@ -280,7 +280,7 @@ module Formulary
end
end
- # Load formulae directly from their contents
+ # Load formulae directly from their contents.
class FormulaContentsLoader < FormulaLoader
# The formula's contents
attr_reader :contents
@@ -298,7 +298,8 @@ module Formulary
end
# Return a Formula instance for the given reference.
- # `ref` is string containing:
+ # `ref` is a string containing:
+ #
# * a formula name
# * a formula pathname
# * a formula URL
diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb
index 0057791b19..9d09992835 100644
--- a/Library/Homebrew/global.rb
+++ b/Library/Homebrew/global.rb
@@ -51,7 +51,7 @@ HOMEBREW_USER_AGENT_FAKE_SAFARI =
"(KHTML, like Gecko) Version/10.0.3 Safari/602.4.8".freeze
# Bintray fallback is here for people auto-updating from a version where
-# HOMEBREW_BOTTLE_DEFAULT_DOMAIN isn't set.
+# `HOMEBREW_BOTTLE_DEFAULT_DOMAIN` isn't set.
HOMEBREW_BOTTLE_DEFAULT_DOMAIN = if ENV["HOMEBREW_BOTTLE_DEFAULT_DOMAIN"]
ENV["HOMEBREW_BOTTLE_DEFAULT_DOMAIN"]
elsif OS.mac?
diff --git a/Library/Homebrew/keg.rb b/Library/Homebrew/keg.rb
index 1ed943c58c..032f3e2e1e 100644
--- a/Library/Homebrew/keg.rb
+++ b/Library/Homebrew/keg.rb
@@ -111,9 +111,8 @@ class Keg
].freeze
# Given an array of kegs, this method will try to find some other kegs
- # that depend on them.
+ # that depend on them. If it does, it returns:
#
- # If it does, it returns:
# - some kegs in the passed array that have installed dependents
# - some installed dependents of those kegs.
#
diff --git a/Library/Homebrew/language/python.rb b/Library/Homebrew/language/python.rb
index 66d6bcabd4..b79ed19505 100644
--- a/Library/Homebrew/language/python.rb
+++ b/Library/Homebrew/language/python.rb
@@ -94,7 +94,7 @@ module Language
end
# Instantiates, creates, and yields a {Virtualenv} object for use from
- # Formula#install, which provides helper methods for instantiating and
+ # {Formula#install}, which provides helper methods for instantiating and
# installing packages into a Python virtualenv.
# @param venv_root [Pathname, String] the path to the root of the virtualenv
# (often `libexec/"venv"`)
@@ -140,7 +140,7 @@ module Language
# Helper method for the common case of installing a Python application.
# Creates a virtualenv in `libexec`, installs all `resource`s defined
# on the formula, and then installs the formula. An options hash may be
- # passed (e.g., :using => "python") to override the default, guessed
+ # passed (e.g., `:using => "python"`) to override the default, guessed
# formula preference for python or python2, or to resolve an ambiguous
# case where it's not clear whether python or python2 should be the
# default guess.
diff --git a/Library/Homebrew/linkage_cache_store.rb b/Library/Homebrew/linkage_cache_store.rb
index b4b6dccfcf..408ad0f22f 100644
--- a/Library/Homebrew/linkage_cache_store.rb
+++ b/Library/Homebrew/linkage_cache_store.rb
@@ -3,11 +3,11 @@ require "cache_store"
#
# `LinkageCacheStore` provides methods to fetch and mutate linkage-specific data used
-# by the `brew linkage` command
+# by the `brew linkage` command.
#
class LinkageCacheStore < CacheStore
- # @param [String] keg_path
- # @param [CacheStoreDatabase] database
+ # @param keg_path [String]
+ # @param database [CacheStoreDatabase]
# @return [nil]
def initialize(keg_path, database)
@keg_path = keg_path
@@ -24,7 +24,7 @@ class LinkageCacheStore < CacheStore
# Inserts dylib-related information into the cache if it does not exist or
# updates data into the linkage cache if it does exist
#
- # @param [Hash] hash_values: hash containing KVPs of { :type => Hash }
+ # @param hash_values [Hash] hash containing KVPs of { :type => Hash }
# @return [nil]
def update!(hash_values)
hash_values.each_key do |type|
@@ -38,7 +38,7 @@ class LinkageCacheStore < CacheStore
database.set @keg_path, hash_values
end
- # @param [Symbol] the type to fetch from the `LinkageCacheStore`
+ # @param type [Symbol] the type to fetch from the `LinkageCacheStore`
# @raise [TypeError] error if the type is not in `HASH_LINKAGE_TYPES`
# @return [Hash]
def fetch(type)
@@ -64,7 +64,7 @@ class LinkageCacheStore < CacheStore
HASH_LINKAGE_TYPES = [:keg_files_dylibs].freeze
- # @param [Symbol] type
+ # @param type [Symbol]
# @return [Hash]
def fetch_hash_values(type)
keg_cache = database.get(@keg_path)
diff --git a/Library/Homebrew/messages.rb b/Library/Homebrew/messages.rb
index 5ee9901ded..55cf102645 100644
--- a/Library/Homebrew/messages.rb
+++ b/Library/Homebrew/messages.rb
@@ -1,5 +1,5 @@
# A Messages object collects messages that may need to be displayed together
-# at the end of a multi-step `brew` command run
+# at the end of a multi-step `brew` command run.
class Messages
attr_reader :caveats, :formula_count, :install_times
diff --git a/Library/Homebrew/migrator.rb b/Library/Homebrew/migrator.rb
index cb3745c5d6..b98d908d2b 100644
--- a/Library/Homebrew/migrator.rb
+++ b/Library/Homebrew/migrator.rb
@@ -137,7 +137,7 @@ class Migrator
@old_pin_link_record = old_pin_record.readlink if @pinned
end
- # Fix INSTALL_RECEIPTS for tap-migrated formula.
+ # Fix INSTALL_RECEIPTs for tap-migrated formula.
def fix_tabs
old_tabs.each do |tab|
tab.tap = formula.tap
@@ -160,7 +160,7 @@ class Migrator
if formula_tap_user == old_tap_user
true
# Homebrew didn't use to update tabs while performing tap-migrations,
- # so there can be INSTALL_RECEIPT's containing wrong information about tap,
+ # so there can be INSTALL_RECEIPTs containing wrong information about tap,
# so we check if there is an entry about oldname migrated to tap and if
# newname's tap is the same as tap to which oldname migrated, then we
# can perform migrations and the taps for oldname and newname are the same.
diff --git a/Library/Homebrew/os/linux/elf.rb b/Library/Homebrew/os/linux/elf.rb
index 26dc0c659b..82789cb570 100644
--- a/Library/Homebrew/os/linux/elf.rb
+++ b/Library/Homebrew/os/linux/elf.rb
@@ -1,5 +1,5 @@
+# @see https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
module ELFShim
- # See: https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header
MAGIC_NUMBER_OFFSET = 0
MAGIC_NUMBER_ASCII = "\x7fELF".freeze
diff --git a/Library/Homebrew/os/mac.rb b/Library/Homebrew/os/mac.rb
index f936e31756..52ca596cd7 100644
--- a/Library/Homebrew/os/mac.rb
+++ b/Library/Homebrew/os/mac.rb
@@ -72,20 +72,23 @@ module OS
@active_developer_dir ||= Utils.popen_read("/usr/bin/xcode-select", "-print-path").strip
end
- # If a specific SDK is requested
- # a) The requested SDK is returned, if it's installed.
- # b) If the requested SDK is not installed, the newest SDK (if any SDKs
+ # If a specific SDK is requested:
+ #
+ # 1. The requested SDK is returned, if it's installed.
+ # 2. If the requested SDK is not installed, the newest SDK (if any SDKs
# are available) is returned.
- # c) If no SDKs are available, nil is returned.
- # If no specific SDK is requested
- # a) For Xcode >= 7, the latest SDK is returned even if the latest SDK is
+ # 3. If no SDKs are available, nil is returned.
+ #
+ # If no specific SDK is requested:
+ #
+ # 1. For Xcode >= 7, the latest SDK is returned even if the latest SDK is
# named after a newer OS version than the running OS. The
- # MACOSX_DEPLOYMENT_TARGET must be set to the OS for which you're
+ # `MACOSX_DEPLOYMENT_TARGET` must be set to the OS for which you're
# actually building (usually the running OS version).
- # https://github.com/Homebrew/legacy-homebrew/pull/50355
- # https://developer.apple.com/library/ios/documentation/DeveloperTools/Conceptual/WhatsNewXcode/Articles/Introduction.html#//apple_ref/doc/uid/TP40004626
+ # - https://github.com/Homebrew/legacy-homebrew/pull/50355
+ # - https://developer.apple.com/library/ios/documentation/DeveloperTools/Conceptual/WhatsNewXcode/Articles/Introduction.html#//apple_ref/doc/uid/TP40004626
# Section "About SDKs and Simulator"
- # b) For Xcode < 7, proceed as if the SDK for the running OS version had
+ # 2. For Xcode < 7, proceed as if the SDK for the running OS version had
# specifically been requested according to the rules above.
def sdk(v = nil)
@@ -98,7 +101,7 @@ module OS
@locator.sdk_if_applicable(v)
end
- # Returns the path to an SDK or nil, following the rules set by #sdk.
+ # Returns the path to an SDK or nil, following the rules set by {.sdk}.
def sdk_path(v = nil)
s = sdk(v)
s&.path
@@ -122,9 +125,10 @@ module OS
end
# See these issues for some history:
- # https://github.com/Homebrew/legacy-homebrew/issues/13
- # https://github.com/Homebrew/legacy-homebrew/issues/41
- # https://github.com/Homebrew/legacy-homebrew/issues/48
+ #
+ # - https://github.com/Homebrew/legacy-homebrew/issues/13
+ # - https://github.com/Homebrew/legacy-homebrew/issues/41
+ # - https://github.com/Homebrew/legacy-homebrew/issues/48
def macports_or_fink
paths = []
diff --git a/Library/Homebrew/os/mac/xquartz.rb b/Library/Homebrew/os/mac/xquartz.rb
index a23701006f..8321d0ca37 100644
--- a/Library/Homebrew/os/mac/xquartz.rb
+++ b/Library/Homebrew/os/mac/xquartz.rb
@@ -60,8 +60,8 @@ module OS
"2.7.11"
end
- # https://xquartz.macosforge.org/trac/wiki
- # https://xquartz.macosforge.org/trac/wiki/Releases
+ # - https://xquartz.macosforge.org/trac/wiki
+ # - https://xquartz.macosforge.org/trac/wiki/Releases
def latest_version
case MacOS.version
when "10.5"
@@ -114,8 +114,8 @@ module OS
end
# This should really be private, but for compatibility reasons it must
- # remain public. New code should use MacOS::X11.bin, MacOS::X11.lib and
- # MacOS::X11.include instead, as that accounts for Xcode-only systems.
+ # remain public. New code should use `MacOS::X11.bin`, `MacOS::X11.lib` and
+ # `MacOS::X11.include` instead, as that accounts for Xcode-only systems.
def prefix
@prefix ||= if Pathname.new("/opt/X11/lib/libpng.dylib").exist?
Pathname.new("/opt/X11")
@@ -139,10 +139,10 @@ module OS
end
# If XQuartz and/or the CLT are installed, headers will be found under
- # /opt/X11/include or /usr/X11/include. For Xcode-only systems, they are
- # found in the SDK, so we use sdk_path for both the headers and libraries.
+ # `/opt/X11/include` or `/usr/X11/include`. For Xcode-only systems, they are
+ # found in the SDK, so we use {.sdk_path} for both the headers and libraries.
# Confusingly, executables (e.g. config scripts) are only found under
- # /opt/X11/bin or /usr/X11/bin in all cases.
+ # `/opt/X11/bin` or `/usr/X11/bin` in all cases.
def effective_prefix
if provided_by_apple? && Xcode.without_clt?
Pathname.new("#{OS::Mac.sdk_path}/usr/X11")
diff --git a/Library/Homebrew/patch.rb b/Library/Homebrew/patch.rb
index a77e8b8eb2..3bb604bf82 100644
--- a/Library/Homebrew/patch.rb
+++ b/Library/Homebrew/patch.rb
@@ -162,7 +162,7 @@ class ExternalPatch
end
end
-# Legacy patches have no checksum and are not cached
+# Legacy patches have no checksum and are not cached.
class LegacyPatch < ExternalPatch
def initialize(strip, url)
super(strip)
diff --git a/Library/Homebrew/requirement.rb b/Library/Homebrew/requirement.rb
index 8dcd865498..f9e8bf9581 100644
--- a/Library/Homebrew/requirement.rb
+++ b/Library/Homebrew/requirement.rb
@@ -49,7 +49,7 @@ class Requirement
s
end
- # Overriding #satisfied? is unsupported.
+ # Overriding {#satisfied?} is unsupported.
# Pass a block or boolean to the satisfy DSL method instead.
def satisfied?
satisfy = self.class.satisfy
@@ -61,7 +61,7 @@ class Requirement
true
end
- # Overriding #fatal? is unsupported.
+ # Overriding {#fatal?} is unsupported.
# Pass a boolean to the fatal DSL method instead.
def fatal?
self.class.fatal || false
@@ -77,7 +77,7 @@ class Requirement
parent
end
- # Overriding #modify_build_environment is unsupported.
+ # Overriding {#modify_build_environment} is unsupported.
# Pass a block to the env DSL method instead.
def modify_build_environment
satisfied?
@@ -196,7 +196,7 @@ class Requirement
class << self
# Expand the requirements of dependent recursively, optionally yielding
- # [dependent, req] pairs to allow callers to apply arbitrary filters to
+ # `[dependent, req]` pairs to allow callers to apply arbitrary filters to
# the list.
# The default filter, which is applied when a block is not given, omits
# optionals and recommendeds based on what the dependent has asked for.
diff --git a/Library/Homebrew/resource.rb b/Library/Homebrew/resource.rb
index 45fb18ad9b..81e820efac 100644
--- a/Library/Homebrew/resource.rb
+++ b/Library/Homebrew/resource.rb
@@ -61,10 +61,10 @@ class Resource
downloader.clear_cache
end
- # Verifies download and unpacks it
+ # Verifies download and unpacks it.
# The block may call `|resource,staging| staging.retain!` to retain the staging
# directory. Subclasses that override stage should implement the tmp
- # dir using Resource#mktemp so that works with all subtypes.
+ # dir using {Mktemp} so that works with all subtypes.
def stage(target = nil, &block)
unless target || block
raise ArgumentError, "target directory or block is required"
@@ -91,8 +91,8 @@ class Resource
end
# If a target is given, unpack there; else unpack to a temp folder.
- # If block is given, yield to that block with |stage|, where stage
- # is a ResourceStagingContext.
+ # If block is given, yield to that block with `|stage|`, where stage
+ # is a {ResourceStageContext}.
# A target or a block must be given, but not both.
def unpack(target = nil)
mktemp(download_name) do |staging|
@@ -210,15 +210,15 @@ class Resource
end
end
-# The context in which a Resource.stage() occurs. Supports access to both
-# the Resource and associated Mktemp in a single block argument. The interface
-# is back-compatible with Resource itself as used in that context.
+# The context in which a {Resource.stage} occurs. Supports access to both
+# the {Resource} and associated {Mktemp} in a single block argument. The interface
+# is back-compatible with {Resource} itself as used in that context.
class ResourceStageContext
extend Forwardable
- # The Resource that is being staged
+ # The {Resource} that is being staged
attr_reader :resource
- # The Mktemp in which @resource is staged
+ # The {Mktemp} in which {#resource} is staged
attr_reader :staging
def_delegators :@resource, :version, :url, :mirrors, :specs, :using, :source_modified_time
diff --git a/Library/Homebrew/rubocops/class_cop.rb b/Library/Homebrew/rubocops/class_cop.rb
index f6586e0054..0702e59fd5 100644
--- a/Library/Homebrew/rubocops/class_cop.rb
+++ b/Library/Homebrew/rubocops/class_cop.rb
@@ -68,7 +68,7 @@ module RuboCop
end
module FormulaAuditStrict
- # - `test do ..end` should be meaningfully defined in the formula
+ # - `test do ..end` should be meaningfully defined in the formula.
class Test < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
test = find_block(body_node, :test)
diff --git a/Library/Homebrew/rubocops/components_order_cop.rb b/Library/Homebrew/rubocops/components_order_cop.rb
index 9bde0804cb..efce883d8d 100644
--- a/Library/Homebrew/rubocops/components_order_cop.rb
+++ b/Library/Homebrew/rubocops/components_order_cop.rb
@@ -3,9 +3,9 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
- # This cop checks for correct order of components in a Formula
+ # This cop checks for correct order of components in Formulae.
#
- # - component_precedence_list has component hierarchy in a nested list
+ # - `component_precedence_list` has component hierarchy in a nested list
# where each sub array contains components' details which are at same precedence level
class ComponentsOrder < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
@@ -96,9 +96,9 @@ module RuboCop
end
end
- # Reorder two nodes in the source, using the corrector instance in autocorrect method
- # Components of same type are grouped together when rewriting the source
- # Linebreaks are introduced if components are of two different methods/blocks/multilines
+ # Reorder two nodes in the source, using the corrector instance in autocorrect method.
+ # Components of same type are grouped together when rewriting the source.
+ # Linebreaks are introduced if components are of two different methods/blocks/multilines.
def reorder_components(corrector, node1, node2)
# order_idx : node1's index in component_precedence_list
# curr_p_idx: node1's index in preceding_comp_arr
diff --git a/Library/Homebrew/rubocops/components_redundancy_cop.rb b/Library/Homebrew/rubocops/components_redundancy_cop.rb
index a0fe004a89..881b4fee75 100644
--- a/Library/Homebrew/rubocops/components_redundancy_cop.rb
+++ b/Library/Homebrew/rubocops/components_redundancy_cop.rb
@@ -3,11 +3,11 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
- # This cop checks if redundant components are present and other component errors
+ # This cop checks if redundant components are present and other component errors.
#
# - `url|checksum|mirror` should be inside `stable` block
# - `head` and `head do` should not be simultaneously present
- # - `bottle :unneeded/:disable` and `bottle do` should not be simultaneously present
+ # - `bottle :unneeded`/`:disable` and `bottle do` should not be simultaneously present
# - `stable do` should not be present without a `head` or `devel` spec
class ComponentsRedundancy < FormulaCop
diff --git a/Library/Homebrew/rubocops/conflicts_cop.rb b/Library/Homebrew/rubocops/conflicts_cop.rb
index ff4d591074..8fa0547db6 100644
--- a/Library/Homebrew/rubocops/conflicts_cop.rb
+++ b/Library/Homebrew/rubocops/conflicts_cop.rb
@@ -4,7 +4,7 @@ require "extend/string"
module RuboCop
module Cop
module FormulaAudit
- # This cop audits versioned Formulae for `conflicts_with`
+ # This cop audits versioned Formulae for `conflicts_with`.
class Conflicts < FormulaCop
MSG = "Versioned formulae should not use `conflicts_with`. " \
"Use `keg_only :versioned_formula` instead.".freeze
diff --git a/Library/Homebrew/rubocops/dependency_order_cop.rb b/Library/Homebrew/rubocops/dependency_order_cop.rb
index 0648b22cd0..82934e146a 100644
--- a/Library/Homebrew/rubocops/dependency_order_cop.rb
+++ b/Library/Homebrew/rubocops/dependency_order_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
- # This cop checks for correct order of `depends_on` in a Formula
+ # This cop checks for correct order of `depends_on` in Formulae.
#
# precedence order:
# build-time > run-time > normal > recommended > optional
diff --git a/Library/Homebrew/rubocops/extend/formula_cop.rb b/Library/Homebrew/rubocops/extend/formula_cop.rb
index 7e11c4cd78..59b71d0156 100644
--- a/Library/Homebrew/rubocops/extend/formula_cop.rb
+++ b/Library/Homebrew/rubocops/extend/formula_cop.rb
@@ -30,7 +30,7 @@ module RuboCop
end
# Checks for regex match of pattern in the node and
- # Sets the appropriate instance variables to report the match
+ # sets the appropriate instance variables to report the match
def regex_match_group(node, pattern)
string_repr = string_content(node)
match_object = string_repr.match(pattern)
@@ -51,9 +51,9 @@ module RuboCop
match_object
end
- # Yields to block when there is a match
- # Parameters: urls : Array of url/mirror method call nodes
- # regex: regex pattern to match urls
+ # Yields to block when there is a match.
+ # @param urls [Array] url/mirror method call nodes
+ # @param regex [Regexp] pattern to match urls
def audit_urls(urls, regex)
urls.each do |url_node|
url_string_node = parameters(url_node).first
@@ -104,8 +104,8 @@ module RuboCop
node.each_child_node(:send).select { |method_node| method_name == method_node.method_name }
end
- # Returns an array of method call nodes matching method_name in every descendant of node
- # Returns every method call if no method_name is passed
+ # Returns an array of method call nodes matching method_name in every descendant of node.
+ # Returns every method call if no method_name is passed.
def find_every_method_call_by_name(node, method_name = nil)
return if node.nil?
@@ -115,10 +115,11 @@ module RuboCop
end
end
- # Returns array of function call nodes matching func_name in every descendant of node
- # Ex. function call: foo(*args, **kwargs)
- # Does not match method calls: foo.bar(*args, **kwargs)
- # Returns every function calls if no func_name is passed
+ # Returns array of function call nodes matching func_name in every descendant of node.
+ #
+ # - matches function call: `foo(*args, **kwargs)`
+ # - does not match method calls: `foo.bar(*args, **kwargs)`
+ # - returns every function calls if no func_name is passed
def find_every_func_call_by_name(node, func_name = nil)
return if node.nil?
@@ -139,12 +140,13 @@ module RuboCop
end
end
- # Matches a method with a receiver,
- # EX: to match `Formula.factory(name)`
- # call `find_instance_method_call(node, "Formula", :factory)`
- # EX: to match `build.head?`
- # call `find_instance_method_call(node, :build, :head?)`
- # yields to a block with matching method node
+ # Matches a method with a receiver.
+ #
+ # - e.g. to match `Formula.factory(name)`
+ # call `find_instance_method_call(node, "Formula", :factory)`
+ # - e.g. to match `build.head?`
+ # call `find_instance_method_call(node, :build, :head?)`
+ # - yields to a block with matching method node
def find_instance_method_call(node, instance, method_name)
methods = find_every_method_call_by_name(node, method_name)
methods.each do |method|
@@ -160,10 +162,11 @@ module RuboCop
end
end
- # Matches receiver part of method,
- # EX: to match `ARGV.()`
- # call `find_instance_call(node, "ARGV")`
- # yields to a block with parent node of receiver
+ # Matches receiver part of method.
+ #
+ # - e.g. to match `ARGV.()`
+ # call `find_instance_call(node, "ARGV")`
+ # - yields to a block with parent node of receiver
def find_instance_call(node, name)
node.each_descendant(:send) do |method_node|
next if method_node.receiver.nil?
@@ -178,8 +181,8 @@ module RuboCop
end
end
- # Returns nil if does not depend on dependency_name
- # args: node - dependency_name - dependency's name
+ # Returns nil if does not depend on dependency_name.
+ # @param dependency_name dependency's name
def depends_on?(dependency_name, *types)
types = [:any] if types.empty?
dependency_nodes = find_every_method_call_by_name(@body, :depends_on)
@@ -192,7 +195,7 @@ module RuboCop
@offensive_node = dependency_nodes[idx]
end
- # Returns true if given dependency name and dependency type exist in given dependency method call node
+ # Returns true if given dependency name and dependency type exist in given dependency method call node.
# TODO: Add case where key of hash is an array
def depends_on_name_type?(node, name = nil, type = :required)
if name
@@ -223,8 +226,8 @@ module RuboCop
type_match && name_match
end
- # Find CONSTANTs in the source
- # if block given, yield matching nodes
+ # Find CONSTANTs in the source.
+ # If block given, yield matching nodes.
def find_const(node, const_name)
return if node.nil?
@@ -284,7 +287,7 @@ module RuboCop
node.each_child_node(:block).select { |block_node| block_name == block_node.method_name }
end
- # Returns an array of block nodes of any depth below node in AST
+ # Returns an array of block nodes of any depth below node in AST.
# If a block is given then yields matching block node to the block!
def find_all_blocks(node, block_name)
return if node.nil?
@@ -298,8 +301,8 @@ module RuboCop
end
end
- # Returns a method definition node with method_name
- # Returns first method def if method_name is nil
+ # Returns a method definition node with method_name.
+ # Returns first method def if method_name is nil.
def find_method_def(node, method_name = nil)
return if node.nil?
@@ -332,8 +335,8 @@ module RuboCop
false
end
- # Check if method_name is called among the direct children nodes in the given node
- # Check if the node itself is the method
+ # Check if method_name is called among the direct children nodes in the given node.
+ # Check if the node itself is the method.
def method_called?(node, method_name)
if node.send_type? && node.method_name == method_name
offending_node(node)
@@ -400,8 +403,8 @@ module RuboCop
end
# Returns true if the given parameters are present in method call
- # and sets the method call as the offending node
- # params can be string, symbol, array, hash, matching regex
+ # and sets the method call as the offending node.
+ # Params can be string, symbol, array, hash, matching regex.
def parameters_passed?(method_node, *params)
method_params = parameters(method_node)
@offensive_node = method_node
diff --git a/Library/Homebrew/rubocops/formula_desc_cop.rb b/Library/Homebrew/rubocops/formula_desc_cop.rb
index c41313fbfe..4f856916de 100644
--- a/Library/Homebrew/rubocops/formula_desc_cop.rb
+++ b/Library/Homebrew/rubocops/formula_desc_cop.rb
@@ -4,7 +4,7 @@ require "extend/string"
module RuboCop
module Cop
module FormulaAudit
- # This cop audits `desc` in Formulae
+ # This cop audits `desc` in Formulae.
#
# - Checks for existence of `desc`
# - Checks if size of `desc` > 80
@@ -37,7 +37,7 @@ module RuboCop
end
module FormulaAuditStrict
- # This cop audits `desc` in Formulae
+ # This cop audits `desc` in Formulae.
#
# - Checks for leading/trailing whitespace in `desc`
# - Checks if `desc` begins with an article
diff --git a/Library/Homebrew/rubocops/homepage_cop.rb b/Library/Homebrew/rubocops/homepage_cop.rb
index 1c07f2896b..630037d4c7 100644
--- a/Library/Homebrew/rubocops/homepage_cop.rb
+++ b/Library/Homebrew/rubocops/homepage_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
- # This cop audits `homepage` url in Formulae
+ # This cop audits the `homepage` URL in Formulae.
class Homepage < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
homepage_node = find_node_method_by_name(body_node, :homepage)
diff --git a/Library/Homebrew/rubocops/lines_cop.rb b/Library/Homebrew/rubocops/lines_cop.rb
index ca5dbc4c1d..24a2637e61 100644
--- a/Library/Homebrew/rubocops/lines_cop.rb
+++ b/Library/Homebrew/rubocops/lines_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
- # This cop checks for various miscellaneous Homebrew coding styles
+ # This cop checks for various miscellaneous Homebrew coding styles.
class Lines < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, _body_node)
[:automake, :ant, :autoconf, :emacs, :expat, :libtool, :mysql, :perl,
diff --git a/Library/Homebrew/rubocops/options_cop.rb b/Library/Homebrew/rubocops/options_cop.rb
index e16681e58b..ddd08e6866 100644
--- a/Library/Homebrew/rubocops/options_cop.rb
+++ b/Library/Homebrew/rubocops/options_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
- # This cop audits `options` in Formulae
+ # This cop audits `options` in Formulae.
class Options < FormulaCop
DEPRECATION_MSG = "macOS has been 64-bit only since 10.6 so 32-bit options are deprecated.".freeze
diff --git a/Library/Homebrew/rubocops/patches_cop.rb b/Library/Homebrew/rubocops/patches_cop.rb
index b7b632ae16..db17cf102a 100644
--- a/Library/Homebrew/rubocops/patches_cop.rb
+++ b/Library/Homebrew/rubocops/patches_cop.rb
@@ -4,7 +4,7 @@ require "extend/string"
module RuboCop
module Cop
module FormulaAudit
- # This cop audits patches in Formulae
+ # This cop audits patches in Formulae.
class Patches < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body)
external_patches = find_all_blocks(body, :patch)
diff --git a/Library/Homebrew/rubocops/urls_cop.rb b/Library/Homebrew/rubocops/urls_cop.rb
index ec8d7415ac..8ef40e9144 100644
--- a/Library/Homebrew/rubocops/urls_cop.rb
+++ b/Library/Homebrew/rubocops/urls_cop.rb
@@ -3,7 +3,7 @@ require "rubocops/extend/formula_cop"
module RuboCop
module Cop
module FormulaAudit
- # This cop audits urls and mirrors in Formulae
+ # This cop audits URLs and mirrors in Formulae.
class Urls < FormulaCop
def audit_formula(_node, _class_node, _parent_class_node, body_node)
urls = find_every_func_call_by_name(body_node, :url)
diff --git a/Library/Homebrew/software_spec.rb b/Library/Homebrew/software_spec.rb
index b7a81d645d..59a351a1b5 100644
--- a/Library/Homebrew/software_spec.rb
+++ b/Library/Homebrew/software_spec.rb
@@ -359,7 +359,7 @@ class BottleSpecification
cellar == :any || cellar == :any_skip_relocation || cellar == HOMEBREW_CELLAR.to_s
end
- # Does the Bottle this BottleSpecification belongs to need to be relocated?
+ # Does the {Bottle} this BottleSpecification belongs to need to be relocated?
def skip_relocation?
cellar == :any_skip_relocation
end
diff --git a/Library/Homebrew/tap.rb b/Library/Homebrew/tap.rb
index 6a17b57330..19c32aa57b 100644
--- a/Library/Homebrew/tap.rb
+++ b/Library/Homebrew/tap.rb
@@ -2,7 +2,7 @@ require "extend/cachable"
require "readall"
require "description_cache_store"
-# a {Tap} is used to extend the formulae provided by Homebrew core.
+# A {Tap} is used to extend the formulae provided by Homebrew core.
# Usually, it's synced with a remote git repository. And it's likely
# a GitHub repository with the name of `user/homebrew-repo`. In such
# case, `user/repo` will be used as the {#name} of this {Tap}, where
@@ -55,7 +55,7 @@ class Tap
extend Enumerable
# The user name of this {Tap}. Usually, it's the GitHub username of
- # this #{Tap}'s remote repository.
+ # this {Tap}'s remote repository.
attr_reader :user
# The repository name of this {Tap} without leading `homebrew-`.
@@ -87,7 +87,7 @@ class Tap
@alias_reverse_table = nil
end
- # clear internal cache
+ # Clear internal cache
def clear_cache
@remote = nil
@repo_var = nil
@@ -153,7 +153,7 @@ class Tap
path.git_short_head
end
- # time since git last commit for this {Tap}.
+ # Time since git last commit for this {Tap}.
def git_last_commit
raise TapUnavailableError, name unless installed?
@@ -224,7 +224,7 @@ class Tap
false
end
- # install this {Tap}.
+ # Install this {Tap}.
#
# @param [Hash] options
# @option options [String] :clone_target If passed, it will be used as the clone remote.
@@ -324,7 +324,7 @@ class Tap
Utils::Link.link_completions(path, command)
end
- # uninstall this {Tap}.
+ # Uninstall this {Tap}.
def uninstall
require "descriptions"
raise TapUnavailableError, name unless installed?
@@ -354,7 +354,7 @@ class Tap
remote.casecmp(default_remote).nonzero?
end
- # path to the directory of all {Formula} files for this {Tap}.
+ # Path to the directory of all {Formula} files for this {Tap}.
def formula_dir
@formula_dir ||= potential_formula_dirs.find(&:directory?) || path/"Formula"
end
@@ -363,7 +363,7 @@ class Tap
@potential_formula_dirs ||= [path/"Formula", path/"HomebrewFormula", path].freeze
end
- # path to the directory of all {Cask} files for this {Tap}.
+ # Path to the directory of all {Cask} files for this {Tap}.
def cask_dir
@cask_dir ||= path/"Casks"
end
@@ -386,7 +386,7 @@ class Tap
contents
end
- # an array of all {Formula} files of this {Tap}.
+ # An array of all {Formula} files of this {Tap}.
def formula_files
@formula_files ||= if formula_dir.directory?
formula_dir.children.select(&method(:ruby_file?))
@@ -395,7 +395,7 @@ class Tap
end
end
- # an array of all {Cask} files of this {Tap}.
+ # An array of all {Cask} files of this {Tap}.
def cask_files
@cask_files ||= if cask_dir.directory?
cask_dir.children.select(&method(:ruby_file?))
@@ -428,7 +428,7 @@ class Tap
ruby_file?(file) && file.parent == cask_dir
end
- # an array of all {Formula} names of this {Tap}.
+ # An array of all {Formula} names of this {Tap}.
def formula_names
@formula_names ||= formula_files.map { |f| formula_file_to_name(f) }
end
@@ -487,7 +487,7 @@ class Tap
(file.executable? || file.extname == ".rb")
end
- # an array of all commands files of this {Tap}.
+ # An array of all commands files of this {Tap}.
def command_files
@command_files ||= if command_dir.directory?
command_dir.children.select(&method(:command_file?))
@@ -509,7 +509,7 @@ class Tap
@pinned = pinned_symlink_path.directory?
end
- # pin this {Tap}.
+ # Pin this {Tap}.
def pin
raise TapUnavailableError, name unless installed?
raise TapPinStatusError.new(name, true) if pinned?
@@ -518,7 +518,7 @@ class Tap
@pinned = true
end
- # unpin this {Tap}.
+ # Unpin this {Tap}.
def unpin
raise TapUnavailableError, name unless installed?
raise TapPinStatusError.new(name, false) unless pinned?
@@ -591,12 +591,12 @@ class Tap
end
end
- # an array of all installed {Tap} names.
+ # An array of all installed {Tap} names.
def self.names
map(&:name).sort
end
- # an array of all tap cmd directory {Pathname}s
+ # An array of all tap cmd directory {Pathname}s
def self.cmd_directories
Pathname.glob TAP_DIRECTORY/"*/*/cmd"
end
@@ -633,7 +633,7 @@ class Tap
end
end
-# A specialized {Tap} class for the core formulae
+# A specialized {Tap} class for the core formulae.
class CoreTap < Tap
def default_remote
"https://github.com/Homebrew/homebrew-core".freeze
@@ -722,7 +722,7 @@ class CoreTap < Tap
end
end
-# Permanent configuration per {Tap} using `git-config(1)`
+# Permanent configuration per {Tap} using `git-config(1)`.
class TapConfig
attr_reader :tap
diff --git a/Library/Homebrew/utils.rb b/Library/Homebrew/utils.rb
index c34ec720cf..8d20dc2444 100644
--- a/Library/Homebrew/utils.rb
+++ b/Library/Homebrew/utils.rb
@@ -303,7 +303,7 @@ def safe_system(cmd, *args, **options)
raise(ErrorDuringExecution.new([cmd, *args], status: $CHILD_STATUS))
end
-# prints no output
+# Prints no output
def quiet_system(cmd, *args)
Homebrew._system(cmd, *args) do
# Redirect output streams to `/dev/null` instead of closing as some programs
@@ -504,9 +504,9 @@ end
# Calls the given block with the passed environment variables
# added to ENV, then restores ENV afterwards.
# Example:
-# with_env(PATH: "/bin") do
+# with_env(PATH: "/bin") do
# system "echo $PATH"
-# end
+# end
#
# Note that this method is *not* thread-safe - other threads
# which happen to be scheduled during the block will also
diff --git a/Library/Homebrew/utils/inreplace.rb b/Library/Homebrew/utils/inreplace.rb
index f7d06db5aa..67881953d0 100644
--- a/Library/Homebrew/utils/inreplace.rb
+++ b/Library/Homebrew/utils/inreplace.rb
@@ -13,8 +13,9 @@ module Utils
# prefer a patch but if you need the `prefix` of this formula in the
# patch you have to resort to `inreplace`, because in the patch
# you don't have access to any var defined by the formula. Only
- # HOMEBREW_PREFIX is available in the embedded patch.
- # inreplace supports regular expressions.
+ # `HOMEBREW_PREFIX` is available in the embedded patch.
+ #
+ # `inreplace` supports regular expressions:
# inreplace "somefile.cfg", /look[for]what?/, "replace by #{bin}/tool"
def inreplace(paths, before = nil, after = nil, audit_result = true)
errors = {}
diff --git a/Library/Homebrew/utils/shell.rb b/Library/Homebrew/utils/shell.rb
index 9a886ca40d..d53741603e 100644
--- a/Library/Homebrew/utils/shell.rb
+++ b/Library/Homebrew/utils/shell.rb
@@ -35,7 +35,7 @@ module Utils
end
end
- # return the shell profile file based on users' preferred shell
+ # return the shell profile file based on user's preferred shell
def profile
SHELL_PROFILE_MAP.fetch(preferred, "~/.bash_profile")
end