From b745546943a05bd2aa6d129e9a44e29771bf115a Mon Sep 17 00:00:00 2001
From: Mike McQuaid
Date: Sun, 6 Dec 2015 22:18:16 +0000
Subject: Overhaul, simplify and cleanup documentation.

Remove duplication, link to the API documentation more often,
tweak wording, add `@UniqMartin` as a maintainer, note `@jacknagel`'s
and `@adamv`'s significant past contributions to Homebrew, delete some
outdated or unneeded documentation, add some missing `Formula` API.
entries and simplify/improve `CONTRIBUTING.md`.

Closes Homebrew/homebrew#46179.

Closes Homebrew/homebrew#46618.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
---
 Library/Homebrew/formula.rb          | 10 ++++++++--
 Library/Homebrew/language/haskell.rb |  2 +-
 Library/Homebrew/manpages/brew.1.md  | 10 ++++++----
 3 files changed, 15 insertions(+), 7 deletions(-)

(limited to 'Library/Homebrew')

diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index 6de23f7b0..c4fad6793 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -723,11 +723,12 @@ class Formula
   end
   alias_method :startup_plist, :plist
 
-  # The {.plist} name (the name of the launchd service).
+  # The generated launchd {.plist} service name.
   def plist_name
     "homebrew.mxcl."+name
   end
 
+  # The generated launchd {.plist} file path.
   def plist_path
     prefix+(plist_name+".plist")
   end
@@ -1627,7 +1628,7 @@ class Formula
     #     `S3DownloadStrategy` (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://some.dont.provide.archives.example.com", :using => :git, :tag => "1.2.3"</pre>
+    # <pre>url "https://some.dont.provide.archives.example.com", :using => :git, :tag => "1.2.3", :revision => "db8e4de5b2d6653f66aea53094624468caad15d2"</pre>
     def url(val, specs = {})
       stable.url(val, specs)
     end
@@ -1853,6 +1854,11 @@ class Formula
       specs.each { |spec| spec.option(name, description) }
     end
 
+    # @!attribute [w] deprecated_option
+    # Deprecated options are used to rename options and migrate users who used
+    # them to newer ones. They are mostly used for migrating non-`with` options
+    # (e.g. `enable-debug`) to `with` options (e.g. `with-debug`).
+    # <pre>deprecated_option "enable-debug" => "with-debug"</pre>
     def deprecated_option(hash)
       specs.each { |spec| spec.deprecated_option(hash) }
     end
diff --git a/Library/Homebrew/language/haskell.rb b/Library/Homebrew/language/haskell.rb
index e7163a231..569ed155f 100644
--- a/Library/Homebrew/language/haskell.rb
+++ b/Library/Homebrew/language/haskell.rb
@@ -1,6 +1,6 @@
 module Language
   module Haskell
-    # module for formulas using cabal-install as build tool
+    # module for formulae using cabal-install as build tool
     module Cabal
       module ClassMethods
         def setup_ghc_compilers
diff --git a/Library/Homebrew/manpages/brew.1.md b/Library/Homebrew/manpages/brew.1.md
index e1dc1e432..15f4b2add 100644
--- a/Library/Homebrew/manpages/brew.1.md
+++ b/Library/Homebrew/manpages/brew.1.md
@@ -592,7 +592,9 @@ can take several different forms:
 
   * `HOMEBREW_BUILD_FROM_SOURCE`:
     If set, instructs Homebrew to compile from source even when a formula
-    provides a bottle.
+    provides a bottle. This environment variable is intended for use by
+    Homebrew developers. Please do not file issues if you encounter errors when
+    using this environment variable.
 
   * `HOMEBREW_CACHE`:
     If set, instructs Homebrew to use the given directory as the download cache.
@@ -715,10 +717,10 @@ Homebrew Documentation: <https://github.com/Homebrew/homebrew/blob/master/share/
 
 ## AUTHORS
 
-Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Dominyk Tiller, Tim Smith and Alex Dunn.
+Homebrew's current maintainers are Misty De Meo, Andrew Janke, Xu Cheng, Mike McQuaid, Baptiste Fontaine, Brett Koonce, Martin Afanasjew, Dominyk Tiller, Tim Smith and Alex Dunn.
 
-Homebrew was originally created by Max Howell.
+Former maintainers with significant contributions include Jack Nagel, Adam Vandenberg and Homebrew's creator: Max Howell.
 
 ## BUGS
 
-See Issues on GitHub: <https://github.com/Homebrew/homebrew/issues>
+See our issues on GitHub: <https://github.com/Homebrew/homebrew/issues>
-- 
cgit v1.2.3