Adjust comments to tidy API docs output.

Author: EricFromCanada

.yardopts

@@ -7,7 +7,4 @@
 --exclude Library/Homebrew/compat/
 Library/Homebrew/**/*.rb
 -
-share/doc/homebrew/*.html
-Library/Homebrew/*.md
-share/doc/homebrew/*.md
 *.md

Library/Homebrew/cache_store.rb

@@ -2,7 +2,7 @@
 
 #
 # `CacheStoreDatabase` acts as an interface to a persistent storage mechanism
-# residing in the `HOMEBREW_CACHE`
+# residing in the `HOMEBREW_CACHE`.
 #
 class CacheStoreDatabase
   # Yields the cache store database.
@@ -107,7 +107,7 @@ def cache_path
 
 #
 # `CacheStore` provides methods to mutate and fetch data from a persistent
-# storage mechanism
+# storage mechanism.
 #
 class CacheStore
   # @param  [CacheStoreDatabase] database

Library/Homebrew/cask/cmd/doctor.rb

@@ -42,7 +42,7 @@ def check_software_versions
       end
 
       # This could be done by calling into Homebrew, but the situation
-      # where "doctor" is needed is precisely the situation where such
+      # where `brew doctor` is needed is precisely the situation where such
       # things are less dependable.
       def check_install_location
         ohai "Homebrew Cask Install Location"

Library/Homebrew/cask/installer.rb

@@ -221,9 +221,9 @@ def install_artifacts
       end
     end
 
-    # TODO: move dependencies to a separate class
-    #       dependencies should also apply for "brew cask stage"
-    #       override dependencies with --force or perhaps --force-deps
+    # TODO: move dependencies to a separate class,
+    #       dependencies should also apply for `brew cask stage`,
+    #       override dependencies with `--force` or perhaps `--force-deps`
     def satisfy_dependencies
       return unless @cask.depends_on
 

Library/Homebrew/cleaner.rb

@@ -1,8 +1,9 @@
 # Cleans a newly installed keg.
 # By default:
-# * removes .la files
-# * removes perllocal.pod files
-# * removes .packlist files
+#
+# * removes `.la` files
+# * removes `perllocal.pod` files
+# * removes `.packlist` files
 # * removes empty directories
 # * sets permissions on executables
 # * removes unresolved symlinks

Library/Homebrew/cmd/upgrade.rb

@@ -91,8 +91,8 @@ def upgrade
   def upgrade_formulae(formulae_to_install)
     return if formulae_to_install.empty?
 
-    # Sort keg_only before non-keg_only formulae to avoid any needless conflicts
-    # with outdated, non-keg_only versions of formulae being upgraded.
+    # Sort keg-only before non-keg-only formulae to avoid any needless conflicts
+    # with outdated, non-keg-only versions of formulae being upgraded.
     formulae_to_install.sort! do |a, b|
       if !a.keg_only? && b.keg_only?
         1

Library/Homebrew/config.rb

@@ -2,13 +2,13 @@
   raise "HOMEBREW_BREW_FILE was not exported! Please call bin/brew directly!"
 end
 
-# Path to `bin/brew` main executable in HOMEBREW_PREFIX
+# Path to `bin/brew` main executable in `HOMEBREW_PREFIX`
 HOMEBREW_BREW_FILE = Pathname.new(ENV["HOMEBREW_BREW_FILE"])
 
 # Where we link under
 HOMEBREW_PREFIX = Pathname.new(ENV["HOMEBREW_PREFIX"])
 
-# Where .git is found
+# Where `.git` is found
 HOMEBREW_REPOSITORY = Pathname.new(ENV["HOMEBREW_REPOSITORY"])
 
 # Where we store most of Homebrew, taps, and various metadata
@@ -38,7 +38,7 @@
 # Where build, postinstall, and test logs of formulae are written to
 HOMEBREW_LOGS = Pathname.new(ENV["HOMEBREW_LOGS"] || "~/Library/Logs/Homebrew/").expand_path
 
-# Must use /tmp instead of $TMPDIR because long paths break Unix domain sockets
+# Must use `/tmp` instead of `TMPDIR` because long paths break Unix domain sockets
 HOMEBREW_TEMP = begin
   # /tmp fallback is here for people auto-updating from a version where
   # HOMEBREW_TEMP isn't set.

Library/Homebrew/cxxstdlib.rb

@@ -40,10 +40,10 @@ def initialize(type, compiler)
     @compiler = compiler.to_sym
   end
 
-  # If either package doesn't use C++, all is well
-  # libstdc++ and libc++ aren't ever intercompatible
+  # If either package doesn't use C++, all is well.
+  # libstdc++ and libc++ aren't ever intercompatible.
   # libstdc++ is compatible across Apple compilers, but
-  # not between Apple and GNU compilers, or between GNU compiler versions
+  # not between Apple and GNU compilers, or between GNU compiler versions.
   def compatible_with?(other)
     return true if type.nil? || other.type.nil?
 

Library/Homebrew/dependable.rb

@@ -1,7 +1,7 @@
 require "options"
 
 module Dependable
-  # :run and :linked are no longer used but keep them here to avoid them being
+  # `:run` and `:linked` are no longer used but keep them here to avoid them being
   # misused in future.
   RESERVED_TAGS = [:build, :optional, :recommended, :run, :test, :linked].freeze
 

Library/Homebrew/dependency.rb

@@ -71,7 +71,7 @@ def self._load(marshaled)
 
   class << self
     # Expand the dependencies of dependent recursively, optionally yielding
-    # [dependent, dep] pairs to allow callers to apply arbitrary filters to
+    # `[dependent, dep]` 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.

Library/Homebrew/description_cache_store.rb

@@ -4,24 +4,24 @@
 
 #
 # `DescriptionCacheStore` provides methods to fetch and mutate linkage-specific data used
-# by the `brew linkage` command
+# by the `brew linkage` command.
 #
 class DescriptionCacheStore < CacheStore
   include Searchable
 
   # Inserts a formula description into the cache if it does not exist or
-  # updates the formula description if it does exist
+  # updates the formula description if it does exist.
   #
-  # @param  [String] formula_name: the name of the formula to set
-  # @param  [String] description:  the description from the formula to set
+  # @param formula_name [String] the name of the formula to set
+  # @param description  [String] the description from the formula to set
   # @return [nil]
   def update!(formula_name, description)
     database.set(formula_name, description)
   end
 
-  # Delete the formula description from the `DescriptionCacheStore`
+  # Delete the formula description from the `DescriptionCacheStore`.
   #
-  # @param  [String] formula_name: the name of the formula to delete
+  # @param formula_name [String] the name of the formula to delete
   # @return [nil]
   def delete!(formula_name)
     database.delete(formula_name)
@@ -37,7 +37,7 @@ def populate_if_empty!
 
   # Use an update report to update the `DescriptionCacheStore`.
   #
-  # @param  [Report] report: an update report generated by cmd/update.rb
+  # @param report [Report] an update report generated by cmd/update.rb
   # @return [nil]
   def update_from_report!(report)
     return populate_if_empty! if database.empty?
@@ -55,7 +55,7 @@ def update_from_report!(report)
 
   # Use an array of formulae names to update the `DescriptionCacheStore`.
   #
-  # @param  [Array] formula_names: the formulae to update.
+  # @param formula_names [Array] the formulae to update
   # @return [nil]
   def update_from_formula_names!(formula_names)
     return populate_if_empty! if database.empty?
@@ -71,7 +71,7 @@ def update_from_formula_names!(formula_names)
 
   # Use an array of formulae names to delete them from the `DescriptionCacheStore`.
   #
-  # @param  [Array] formula_names: the formulae to delete.
+  # @param formula_names [Array] the formulae to delete
   # @return [nil]
   def delete_from_formula_names!(formula_names)
     return if database.empty?

Library/Homebrew/dev-cmd/pull.rb

@@ -453,9 +453,9 @@ def files_changed_in_patch(patchfile, tap)
     { files: files, formulae: formulae, others: others }
   end
 
-  # Get current formula versions without loading formula definition in this process
-  # Returns info as a hash (type => version), for pull.rb's internal use
-  # Uses special key :nonexistent => true for nonexistent formulae
+  # Get current formula versions without loading formula definition in this process.
+  # Returns info as a hash (type => version), for pull.rb's internal use.
+  # Uses special key `:nonexistent => true` for nonexistent formulae.
   def current_versions_from_info_external(formula_name)
     info = FormulaInfoFromJson.lookup(formula_name)
     versions = {}
@@ -540,7 +540,7 @@ def publish_bottle_file_on_bintray(f, bintray_org, creds)
     false
   end
 
-  # Formula info drawn from an external "brew info --json" call
+  # Formula info drawn from an external `brew info --json` call
   class FormulaInfoFromJson
     # The whole info structure parsed from the JSON
     attr_accessor :info
@@ -549,8 +549,8 @@ def initialize(info)
       @info = info
     end
 
-    # Looks up formula on disk and reads its info
-    # Returns nil if formula is absent or if there was an error reading it
+    # Looks up formula on disk and reads its info.
+    # Returns nil if formula is absent or if there was an error reading it.
     def self.lookup(name)
       json = Utils.popen_read(HOMEBREW_BREW_FILE, "info", "--json=v1", name)
 
@@ -600,11 +600,11 @@ def revision
     end
   end
 
-  # Bottle info as used internally by pull, with alternate platform support
+  # Bottle info as used internally by pull, with alternate platform support.
   class BottleInfo
     # URL of bottle as string
     attr_accessor :url
-    # Expected SHA256 as string
+    # Expected SHA-256 as string
     attr_accessor :sha256
 
     def initialize(url, sha256)

Library/Homebrew/diagnostic.rb

@@ -59,8 +59,8 @@ def get_mounts(path = nil)
 
     class Checks
       ############# HELPERS
-      # Finds files in HOMEBREW_PREFIX *and* /usr/local.
-      # Specify paths relative to a prefix eg. "include/foo.h".
+      # Finds files in `HOMEBREW_PREFIX` *and* /usr/local.
+      # Specify paths relative to a prefix e.g. "include/foo.h".
       # Sets @found for your convenience.
       def find_relative_paths(*relative_paths)
         @found = [HOMEBREW_PREFIX, "/usr/local"].uniq.reduce([]) do |found, prefix|

Library/Homebrew/download_strategy.rb

@@ -72,8 +72,8 @@ def chdir
   end
   private :chdir
 
-  # @!attribute [r]
-  # return most recent modified time for all files in the current working directory after stage.
+  # @!attribute [r] source_modified_time
+  # Returns the most recent modified time for all files in the current working directory after stage.
   def source_modified_time
     Pathname.pwd.to_enum(:find).select(&:file?).map(&:mtime).max
   end
@@ -405,7 +405,7 @@ def curl(*args, **options)
   end
 end
 
-# Detect and download from Apache Mirror
+# Detect and download from Apache Mirror.
 class CurlApacheMirrorDownloadStrategy < CurlDownloadStrategy
   def mirrors
     return @combined_mirrors if defined?(@combined_mirrors)
@@ -440,7 +440,7 @@ def apache_mirrors
 end
 
 # Download via an HTTP POST.
-# Query parameters on the URL are converted into POST parameters
+# Query parameters on the URL are converted into POST parameters.
 class CurlPostDownloadStrategy < CurlDownloadStrategy
   private
 
@@ -477,7 +477,7 @@ def initialize(path)
 # S3DownloadStrategy downloads tarballs from AWS S3.
 # To use it, add `:using => :s3` to the URL section of your
 # formula.  This download strategy uses AWS access tokens (in the
-# environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)
+# environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`)
 # to sign the request.  This strategy is good in a corporate setting,
 # because it lets you use a private S3 bucket as a repo for internal
 # distribution.  (It will work for public buckets as well.)
@@ -510,7 +510,7 @@ def _fetch(url:, resolved_url:)
 # Private Repository. To use it, add
 # `:using => :github_private_repo` to the URL section of
 # your formula. This download strategy uses GitHub access tokens (in the
-# environment variables HOMEBREW_GITHUB_API_TOKEN) to sign the request.  This
+# environment variables `HOMEBREW_GITHUB_API_TOKEN`) to sign the request.  This
 # strategy is suitable for corporate use just like S3DownloadStrategy, because
 # it lets you use a private GitHub repository for internal distribution.  It
 # works with public one, but in that case simply use CurlDownloadStrategy.
@@ -568,7 +568,7 @@ def validate_github_repository_access!
 # GitHubPrivateRepositoryReleaseDownloadStrategy downloads tarballs from GitHub
 # Release assets. To use it, add `:using => :github_private_release` to the URL section
 # of your formula. This download strategy uses GitHub access tokens (in the
-# environment variables HOMEBREW_GITHUB_API_TOKEN) to sign the request.
+# environment variables `HOMEBREW_GITHUB_API_TOKEN`) to sign the request.
 class GitHubPrivateRepositoryReleaseDownloadStrategy < GitHubPrivateRepositoryDownloadStrategy
   def parse_url_pattern
     url_pattern = %r{https://github.com/([^/]+)/([^/]+)/releases/download/([^/]+)/(\S+)}
@@ -615,8 +615,7 @@ def fetch_release_metadata
 # authentication. If a public/private keypair is configured, it will not
 # prompt for a password.
 #
-# Usage:
-#
+# @example
 #   class Abc < Formula
 #     url "scp://example.com/src/abc.1.0.tar.gz"
 #     ...