From 4f7719ac2ec87409113ba954da26391b0e70d538 Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Tue, 3 Nov 2020 16:36:48 -0500 Subject: [PATCH] apidoc: update examples' syntax --- Library/Homebrew/build_options.rb | 8 +- Library/Homebrew/formula.rb | 97 ++++++++++----------- Library/Homebrew/language/python.rb | 6 +- Library/Homebrew/rubocops/extend/formula.rb | 18 ++-- 4 files changed, 63 insertions(+), 66 deletions(-) diff --git a/Library/Homebrew/build_options.rb b/Library/Homebrew/build_options.rb index de78b09472..af06250a32 100644 --- a/Library/Homebrew/build_options.rb +++ b/Library/Homebrew/build_options.rb @@ -57,10 +57,10 @@ class BuildOptions # True if a {Formula} is being built with {Formula.head} instead of {Formula.stable}. # 
args << "--some-new-stuff" if build.head?
# 
# If there are multiple conditional arguments use a block instead of lines.
-  #  if build.head?
-  #    args << "--i-want-pizza"
-  #    args << "--and-a-cold-beer" if build.with? "cold-beer"
-  #  end
+ # if build.head? + # args << "--i-want-pizza" + # args << "--and-a-cold-beer" if build.with? "cold-beer" + # end def head? private_include? "HEAD" end diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb index db2b1e5728..430bddfa0d 100644 --- a/Library/Homebrew/formula.rb +++ b/Library/Homebrew/formula.rb @@ -906,28 +906,28 @@ class Formula # 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 # 
def plist; <<~EOS
-  #  
-  #  
-  #  
-  #  
-  #    Label
-  #      #{plist_name}
-  #    ProgramArguments
-  #    
-  #      #{opt_bin}/example
-  #      --do-this
-  #    
-  #    RunAtLoad
-  #    
-  #    KeepAlive
-  #    
-  #    StandardErrorPath
-  #    /dev/null
-  #    StandardOutPath
-  #    /dev/null
-  #  
-  #  
-  #  EOS
+  #   
+  #   
+  #   
+  #   
+  #     Label
+  #       #{plist_name}
+  #     ProgramArguments
+  #     
+  #       #{opt_bin}/example
+  #       --do-this
+  #     
+  #     RunAtLoad
+  #     
+  #     KeepAlive
+  #     
+  #     StandardErrorPath
+  #     /dev/null
+  #     StandardOutPath
+  #     /dev/null
+  #   
+  #   
+  #   EOS
   # end
def plist nil @@ -1368,7 +1368,7 @@ class Formula # Block only executed on macOS. No-op on Linux. # 
on_macos do
-  #   Do something mac specific
+  # # Do something Mac-specific
   # end
def on_macos(&_block) 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. # 
on_linux do
-  #   Do something linux specific
+  # # Do something Linux-specific
   # end
def on_linux(&_block) 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 # use the `args << if ` to append to: # 
args = ["--with-option1", "--with-option2"]
+  # args << "--without-gcc" if ENV.compiler == :clang
   #
   # # Most software still uses `configure` and `make`.
   # # Check with `./configure --help` what our options are.
@@ -1941,7 +1942,7 @@ class Formula
   #                       "--disable-silent-rules", "--prefix=#{prefix}",
   #                       *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"
def system(cmd, *args) verbose_using_dots = Homebrew::EnvConfig.verbose_using_dots? @@ -2315,19 +2316,18 @@ class Formula # @!attribute [w] url # 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 => ...` + # If not inferrable, specify the download strategy with `using: ...`. # # - `:git`, `:hg`, `:svn`, `:bzr`, `:fossil`, `:cvs`, - # - `:curl` (normal file download. Will also extract.) + # - `: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",
-    #     :using => :git,
-    #     :tag => "1.2.3",
-    #     :revision => "db8e4de5b2d6653f66aea53094624468caad15d2"
+ # using: :git, + # tag: "1.2.3", + # revision: "db8e4de5b2d6653f66aea53094624468caad15d2" def url(val, specs = {}) stable.url(val, specs) end @@ -2449,11 +2449,11 @@ class Formula # 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}. # 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. # 
head "https://we.prefer.https.over.git.example.com/.git"
- # 
head "https://example.com/.git", :branch => "name_of_branch", :revision => "abc123"
+ # 
head "https://example.com/.git", branch: "name_of_branch"
# or (if autodetect fails): - # 
head "https://hg.is.awesome.but.git.has.won.example.com/", :using => :hg
+ # 
head "https://hg.is.awesome.but.git.has.won.example.com/", using: :hg
def head(val = nil, specs = {}, &block) @head ||= HeadSoftwareSpec.new(flags: build_flags) if block_given? @@ -2488,7 +2488,6 @@ class Formula # deciding if to use the system provided version or not.) # 
# `:build` means this dep is only needed during build.
     # depends_on "cmake" => :build
- # 
depends_on "homebrew/dupes/tcl-tk" => :optional
# 
# `:recommended` dependencies are built by default.
     # # But a `--without-...` option is generated to opt-out.
     # depends_on "readline" => :recommended
@@ -2502,17 +2501,17 @@ class Formula # 
# Optional and enforce that boost is built with `--with-c++11`.
     # depends_on "boost" => [:optional, "with-c++11"]
# 
# If a dependency is only needed in certain cases:
-    # depends_on "sqlite" if MacOS.version == :catalina
-    # depends_on :xcode # If the formula really needs full Xcode.
-    # depends_on :macos => :mojave # Needs at least macOS Mojave (10.14).
-    # 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 "sqlite" if MacOS.version >= :catalina + # depends_on xcode: :build # If the formula really needs full Xcode to compile. + # depends_on macos: :mojave # Needs at least macOS Mojave (10.14) to run. + # depends_on x11: :optional # X11/XQuartz components. + # 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 later. # 
# It is possible to only depend on something if
     # # `build.with?` or `build.without? "another_formula"`:
     # depends_on "postgresql" if build.without? "sqlite"
- # 
# Python 3.x if the `--with-python` is given to `brew install example`
-    # depends_on "python3" => :optional
+ # 
# Require Python if `--with-python` is passed to `brew install example`:
+    # depends_on "python" => :optional
def depends_on(dep) specs.each { |spec| spec.depends_on(dep) } end @@ -2605,13 +2604,13 @@ class Formula # Defines launchd plist handling. # # Does your plist need to be loaded at startup? - # 
plist_options :startup => true
+ # 
plist_options startup: true
# # Or only when necessary or desired by the user? - # 
plist_options :manual => "foo"
+ # 
plist_options manual: "foo"
# # Or perhaps you'd like to give the user a choice? Ooh fancy. - # 
plist_options :startup => true, :manual => "foo start"
+ # 
plist_options startup: true, manual: "foo start"
def plist_options(options) @plist_startup = options[:startup] @plist_manual = options[:manual] @@ -2622,8 +2621,8 @@ class Formula @conflicts ||= [] end - # If this formula conflicts with another one. - # 
conflicts_with "imagemagick", :because => "because both install 'convert' binaries"
+ # One or more formulae that conflict with this one and why. + # 
conflicts_with "imagemagick", because: "both install `convert` binaries"
def conflicts_with(*names) opts = names.last.is_a?(Hash) ? names.pop : {} 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 # will not be deprecated. # 
deprecate! date: "2020-08-27", because: :unmaintained
- # 
deprecate! date: "2020-08-27", because: "it has been replaced by"
+ # 
deprecate! date: "2020-08-27", because: "has been replaced by foo"
def deprecate!(date: nil, because: nil) odeprecated "`deprecate!` without a reason", "`deprecate! because: \"reason\"`" if because.blank? diff --git a/Library/Homebrew/language/python.rb b/Library/Homebrew/language/python.rb index a90e6e4ad9..7671b840b3 100644 --- a/Library/Homebrew/language/python.rb +++ b/Library/Homebrew/language/python.rb @@ -148,9 +148,9 @@ module Language # installing packages into a Python virtualenv. # @param venv_root [Pathname, String] the path to the root of the virtualenv # (often `libexec/"venv"`) - # @param python [String] which interpreter to use (e.g. "python" - # or "python2") - # @param formula [Formula] the active Formula + # @param python [String] which interpreter to use (e.g. "python3" + # or "python3.x") + # @param formula [Formula] the active {Formula} # @return [Virtualenv] a {Virtualenv} instance def virtualenv_create(venv_root, python = "python", formula = self) ENV.refurbish_args diff --git a/Library/Homebrew/rubocops/extend/formula.rb b/Library/Homebrew/rubocops/extend/formula.rb index f0675de949..2c7c3e449b 100644 --- a/Library/Homebrew/rubocops/extend/formula.rb +++ b/Library/Homebrew/rubocops/extend/formula.rb @@ -127,13 +127,12 @@ module RuboCop 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)` - # 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 + # @example to match `Formula.factory(name)` + # find_instance_method_call(node, "Formula", :factory) + # @example to match `build.head?` + # find_instance_method_call(node, :build, :head?) def find_instance_method_call(node, instance, method_name) methods = find_every_method_call_by_name(node, method_name) methods.each do |method| @@ -149,11 +148,10 @@ module RuboCop 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.()` - # call `find_instance_call(node, "ARGV")` - # - yields to a block with parent node of receiver + # @example to match `ARGV.()` + # find_instance_call(node, "ARGV") def find_instance_call(node, name) node.each_descendant(:send) do |method_node| next if method_node.receiver.nil?