admin/brew
1
0
Fork 0
Code Issues Packages Projects Releases 6 Wiki Activity

apidoc: update examples' syntax

Browse Source
This commit is contained in:
EricFromCanada 2020-11-03 16:36:48 -05:00
parent d293431b87
commit 4f7719ac2e
4 changed files with 63 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Library/Homebrew/build_options.rb
View File

@ -57,10 +57,10 @@ class BuildOptions
# True if a {Formula} is being built with {Formula.head} instead of {Formula.stable}. # True if a {Formula} is being built with {Formula.head} instead of {Formula.stable}.
# <pre>args << "--some-new-stuff" if build.head?</pre> # <pre>args << "--some-new-stuff" if build.head?</pre>
# <pre># If there are multiple conditional arguments use a block instead of lines. # <pre># If there are multiple conditional arguments use a block instead of lines.
# if build.head? # if build.head?
# args << "--i-want-pizza" # args << "--i-want-pizza"
# args << "--and-a-cold-beer" if build.with? "cold-beer" # args << "--and-a-cold-beer" if build.with? "cold-beer"
# end</pre> # end</pre>
def head? def head?
private_include? "HEAD" private_include? "HEAD"
end end

97
Library/Homebrew/formula.rb
View File

@ -906,28 +906,28 @@ class Formula
# This method can be overridden to provide a plist. # This method can be overridden to provide a plist.
# @see https://www.unix.com/man-page/all/5/plist/ Apple's plist(5) man page # @see https://www.unix.com/man-page/all/5/plist/ Apple's plist(5) man page
# <pre>def plist; <<~EOS # <pre>def plist; <<~EOS
# <?xml version="1.0" encoding="UTF-8"?> # <?xml version="1.0" encoding="UTF-8"?>
# <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> # <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
# <plist version="1.0"> # <plist version="1.0">
# <dict> # <dict>
# <key>Label</key> # <key>Label</key>
# <string>#{plist_name}</string> # <string>#{plist_name}</string>
# <key>ProgramArguments</key> # <key>ProgramArguments</key>
# <array> # <array>
# <string>#{opt_bin}/example</string> # <string>#{opt_bin}/example</string>
# <string>--do-this</string> # <string>--do-this</string>
# </array> # </array>
# <key>RunAtLoad</key> # <key>RunAtLoad</key>
# <true/> # <true/>
# <key>KeepAlive</key> # <key>KeepAlive</key>
# <true/> # <true/>
# <key>StandardErrorPath</key> # <key>StandardErrorPath</key>
# <string>/dev/null</string> # <string>/dev/null</string>
# <key>StandardOutPath</key> # <key>StandardOutPath</key>
# <string>/dev/null</string> # <string>/dev/null</string>
# </dict> # </dict>
# </plist> # </plist>
# EOS # EOS
# end</pre> # end</pre>
def plist def plist
nil nil
@ -1368,7 +1368,7 @@ class Formula
# Block only executed on macOS. No-op on Linux. # Block only executed on macOS. No-op on Linux.
# <pre>on_macos do # <pre>on_macos do
# Do something mac specific # # Do something Mac-specific
# end</pre> # end</pre>
def on_macos(&_block) def on_macos(&_block)
raise "No block content defined for on_macos block" unless block_given? raise "No block content defined for on_macos block" unless block_given?
@ -1376,7 +1376,7 @@ class Formula
# Block only executed on Linux. No-op on macOS. # Block only executed on Linux. No-op on macOS.
# <pre>on_linux do # <pre>on_linux do
# Do something linux specific # # Do something Linux-specific
# end</pre> # end</pre>
def on_linux(&_block) def on_linux(&_block)
raise "No block content defined for on_linux block" unless block_given? raise "No block content defined for on_linux block" unless block_given?
@ -1934,6 +1934,7 @@ class Formula
# on options defined above, we usually make a list first and then # on options defined above, we usually make a list first and then
# use the `args << if <condition>` to append to: # use the `args << if <condition>` to append to:
# <pre>args = ["--with-option1", "--with-option2"] # <pre>args = ["--with-option1", "--with-option2"]
# args << "--without-gcc" if ENV.compiler == :clang
# #
# # Most software still uses `configure` and `make`. # # Most software still uses `configure` and `make`.
# # Check with `./configure --help` what our options are. # # Check with `./configure --help` what our options are.
@ -1941,7 +1942,7 @@ class Formula
# "--disable-silent-rules", "--prefix=#{prefix}", # "--disable-silent-rules", "--prefix=#{prefix}",
# *args # our custom arg list (needs `*` to unpack) # *args # our custom arg list (needs `*` to unpack)
# #
# # If there is a "make", "install" available, please use it! # # If there is a "make install" available, please use it!
# system "make", "install"</pre> # system "make", "install"</pre>
def system(cmd, *args) def system(cmd, *args)
verbose_using_dots = Homebrew::EnvConfig.verbose_using_dots? verbose_using_dots = Homebrew::EnvConfig.verbose_using_dots?
@ -2315,19 +2316,18 @@ class Formula
# @!attribute [w] url # @!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. # We prefer `https` for security and proxy reasons.
# If not inferrable, specify the download strategy with `:using => ...` # If not inferrable, specify the download strategy with `using: ...`.
# #
# - `:git`, `:hg`, `:svn`, `:bzr`, `:fossil`, `:cvs`, # - `:git`, `:hg`, `:svn`, `:bzr`, `:fossil`, `:cvs`,
# - `:curl` (normal file download. Will also extract.) # - `:curl` (normal file download, will also extract)
# - `:nounzip` (without extracting) # - `:nounzip` (without extracting)
# - `:post` (download via an HTTP POST) # - `:post` (download via an HTTP POST)
# - `:s3` (download from S3 using signed request)
# #
# <pre>url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"</pre> # <pre>url "https://packed.sources.and.we.prefer.https.example.com/archive-1.2.3.tar.bz2"</pre>
# <pre>url "https://some.dont.provide.archives.example.com", # <pre>url "https://some.dont.provide.archives.example.com",
# :using => :git, # using: :git,
# :tag => "1.2.3", # tag: "1.2.3",
# :revision => "db8e4de5b2d6653f66aea53094624468caad15d2"</pre> # revision: "db8e4de5b2d6653f66aea53094624468caad15d2"</pre>
def url(val, specs = {}) def url(val, specs = {})
stable.url(val, specs) stable.url(val, specs)
end end
@ -2449,11 +2449,11 @@ class Formula
# If called as a method this provides just the {url} for the {SoftwareSpec}. # 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}. # 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. # `master` is the default branch and doesn't need stating with a `branch:` parameter.
# <pre>head "https://we.prefer.https.over.git.example.com/.git"</pre> # <pre>head "https://we.prefer.https.over.git.example.com/.git"</pre>
# <pre>head "https://example.com/.git", :branch => "name_of_branch", :revision => "abc123"</pre> # <pre>head "https://example.com/.git", branch: "name_of_branch"</pre>
# or (if autodetect fails): # or (if autodetect fails):
# <pre>head "https://hg.is.awesome.but.git.has.won.example.com/", :using => :hg</pre> # <pre>head "https://hg.is.awesome.but.git.has.won.example.com/", using: :hg</pre>
def head(val = nil, specs = {}, &block) def head(val = nil, specs = {}, &block)
@head ||= HeadSoftwareSpec.new(flags: build_flags) @head ||= HeadSoftwareSpec.new(flags: build_flags)
if block_given? if block_given?
@ -2488,7 +2488,6 @@ class Formula
# deciding if to use the system provided version or not.) # deciding if to use the system provided version or not.)
# <pre># `:build` means this dep is only needed during build. # <pre># `:build` means this dep is only needed during build.
# depends_on "cmake" => :build</pre> # depends_on "cmake" => :build</pre>
# <pre>depends_on "homebrew/dupes/tcl-tk" => :optional</pre>
# <pre># `:recommended` dependencies are built by default. # <pre># `:recommended` dependencies are built by default.
# # But a `--without-...` option is generated to opt-out. # # But a `--without-...` option is generated to opt-out.
# depends_on "readline" => :recommended</pre> # depends_on "readline" => :recommended</pre>
@ -2502,17 +2501,17 @@ class Formula
# <pre># Optional and enforce that boost is built with `--with-c++11`. # <pre># Optional and enforce that boost is built with `--with-c++11`.
# depends_on "boost" => [:optional, "with-c++11"]</pre> # depends_on "boost" => [:optional, "with-c++11"]</pre>
# <pre># If a dependency is only needed in certain cases: # <pre># If a dependency is only needed in certain cases:
# depends_on "sqlite" if MacOS.version == :catalina # depends_on "sqlite" if MacOS.version >= :catalina
# depends_on :xcode # If the formula really needs full Xcode. # depends_on xcode: :build # If the formula really needs full Xcode to compile.
# depends_on :macos => :mojave # Needs at least macOS Mojave (10.14). # depends_on macos: :mojave # Needs at least macOS Mojave (10.14) to run.
# depends_on :x11 => :optional # X11/XQuartz components. # depends_on x11: :optional # X11/XQuartz components.
# depends_on :osxfuse # Permits the use of the upstream signed binary or our source package. # depends_on :osxfuse # Permits the use of the upstream signed binary or our cask.
# depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and above.</pre> # depends_on :tuntap # Does the same thing as above. This is vital for Yosemite and later.</pre>
# <pre># It is possible to only depend on something if # <pre># It is possible to only depend on something if
# # `build.with?` or `build.without? "another_formula"`: # # `build.with?` or `build.without? "another_formula"`:
# depends_on "postgresql" if build.without? "sqlite"</pre> # depends_on "postgresql" if build.without? "sqlite"</pre>
# <pre># Python 3.x if the `--with-python` is given to `brew install example` # <pre># Require Python if `--with-python` is passed to `brew install example`:
# depends_on "python3" => :optional</pre> # depends_on "python" => :optional</pre>
def depends_on(dep) def depends_on(dep)
specs.each { |spec| spec.depends_on(dep) } specs.each { |spec| spec.depends_on(dep) }
end end
@ -2605,13 +2604,13 @@ class Formula
# Defines launchd plist handling. # Defines launchd plist handling.
# #
# Does your plist need to be loaded at startup? # Does your plist need to be loaded at startup?
# <pre>plist_options :startup => true</pre> # <pre>plist_options startup: true</pre>
# #
# Or only when necessary or desired by the user? # Or only when necessary or desired by the user?
# <pre>plist_options :manual => "foo"</pre> # <pre>plist_options manual: "foo"</pre>
# #
# Or perhaps you'd like to give the user a choice? Ooh fancy. # Or perhaps you'd like to give the user a choice? Ooh fancy.
# <pre>plist_options :startup => true, :manual => "foo start"</pre> # <pre>plist_options startup: true, manual: "foo start"</pre>
def plist_options(options) def plist_options(options)
@plist_startup = options[:startup] @plist_startup = options[:startup]
@plist_manual = options[:manual] @plist_manual = options[:manual]
@ -2622,8 +2621,8 @@ class Formula
@conflicts ||= [] @conflicts ||= []
end end
# If this formula conflicts with another one. # One or more formulae that conflict with this one and why.
# <pre>conflicts_with "imagemagick", :because => "because both install 'convert' binaries"</pre> # <pre>conflicts_with "imagemagick", because: "both install `convert` binaries"</pre>
def conflicts_with(*names) def conflicts_with(*names)
opts = names.last.is_a?(Hash) ? names.pop : {} opts = names.last.is_a?(Hash) ? names.pop : {}
names.each { |name| conflicts << FormulaConflict.new(name, opts[:because]) } names.each { |name| conflicts << FormulaConflict.new(name, opts[:because]) }
@ -2759,7 +2758,7 @@ class Formula
# shown on each installation. If the date has not yet passed the formula # shown on each installation. If the date has not yet passed the formula
# will not be deprecated. # will not be deprecated.
# <pre>deprecate! date: "2020-08-27", because: :unmaintained</pre> # <pre>deprecate! date: "2020-08-27", because: :unmaintained</pre>
# <pre>deprecate! date: "2020-08-27", because: "it has been replaced by"</pre> # <pre>deprecate! date: "2020-08-27", because: "has been replaced by foo"</pre>
def deprecate!(date: nil, because: nil) def deprecate!(date: nil, because: nil)
odeprecated "`deprecate!` without a reason", "`deprecate! because: \"reason\"`" if because.blank? odeprecated "`deprecate!` without a reason", "`deprecate! because: \"reason\"`" if because.blank?

6
Library/Homebrew/language/python.rb
View File

@ -148,9 +148,9 @@ module Language
# installing packages into a Python virtualenv. # installing packages into a Python virtualenv.
# @param venv_root [Pathname, String] the path to the root of the virtualenv # @param venv_root [Pathname, String] the path to the root of the virtualenv
# (often `libexec/"venv"`) # (often `libexec/"venv"`)
# @param python [String] which interpreter to use (e.g. "python" # @param python [String] which interpreter to use (e.g. "python3"
# or "python2") # or "python3.x")
# @param formula [Formula] the active Formula # @param formula [Formula] the active {Formula}
# @return [Virtualenv] a {Virtualenv} instance # @return [Virtualenv] a {Virtualenv} instance
def virtualenv_create(venv_root, python = "python", formula = self) def virtualenv_create(venv_root, python = "python", formula = self)
ENV.refurbish_args ENV.refurbish_args

18
Library/Homebrew/rubocops/extend/formula.rb
View File

@ -127,13 +127,12 @@ module RuboCop
end end
end end
# Matches a method with a receiver. # Matches a method with a receiver. Yields to a block with matching method node.
# #
# - e.g. to match `Formula.factory(name)` # @example to match `Formula.factory(name)`
# call `find_instance_method_call(node, "Formula", :factory)` # find_instance_method_call(node, "Formula", :factory)
# - e.g. to match `build.head?` # @example to match `build.head?`
# call `find_instance_method_call(node, :build, :head?)` # find_instance_method_call(node, :build, :head?)
# - yields to a block with matching method node
def find_instance_method_call(node, instance, method_name) def find_instance_method_call(node, instance, method_name)
methods = find_every_method_call_by_name(node, method_name) methods = find_every_method_call_by_name(node, method_name)
methods.each do |method| methods.each do |method|
@ -149,11 +148,10 @@ module RuboCop
end end
end end
# Matches receiver part of method. # Matches receiver part of method. Yields to a block with parent node of receiver.
# #
# - e.g. to match `ARGV.<whatever>()` # @example to match `ARGV.<whatever>()`
# call `find_instance_call(node, "ARGV")` # find_instance_call(node, "ARGV")
# - yields to a block with parent node of receiver
def find_instance_call(node, name) def find_instance_call(node, name)
node.each_descendant(:send) do |method_node| node.each_descendant(:send) do |method_node|
next if method_node.receiver.nil? next if method_node.receiver.nil?