gist-logs: add proper documentation, improve error handling (#217)

Library/Homebrew/cmd/gist-logs.rb

@@ -1,3 +1,14 @@
+#:  * `gist-logs` [`--new-issue`|`-n`] <formula>:
+#:     Upload logs for a failed build of <formula> to a new Gist.
+#:
+#:     <formula> is usually the name of the formula to install, but it can be specified
+#:     in several different ways. See [SPECIFYING FORMULAE][].
+#:
+#:     If `--new-issue` is passed, automatically create a new issue in the appropriate
+#:     GitHub repository as well as creating the Gist.
+#:
+#:     If no logs are found, an error message is presented.      
+
 require "formula"
 require "system_config"
 require "net/http"
@@ -161,11 +172,7 @@ module Homebrew
   end
 
   def gist_logs
-    if ARGV.resolved_formulae.length != 1
+    raise FormulaUnspecifiedError if ARGV.resolved_formulae.length != 1
-      puts "usage: brew gist-logs [--new-issue|-n] <formula>"
-      Homebrew.failed = true
-      return
-    end
 
     gistify_logs(ARGV.resolved_formulae[0])
   end

Library/Homebrew/cmd/install.rb

@@ -2,7 +2,7 @@
 #:    Install <formula>.
 #:
 #:    <formula> is usually the name of the formula to install, but it can be specified
-#:    several different ways. See [SPECIFYING FORMULAE][].
+#:    in several different ways. See [SPECIFYING FORMULAE][].
 #:
 #:    If `--debug` is passed and brewing fails, open an interactive debugging
 #:    session with access to IRB or a shell inside the temporary build directory.

share/doc/homebrew/brew.1.html

@@ -157,6 +157,15 @@ bottle.</p>
 
 <p>If <code>--force-bottle</code> is passed, download a bottle if it exists for the current
 version of OS X, even if it would not be used during installation.</p></dd>
+<dt><code>gist-logs</code> [<code>--new-issue</code>|<code>-n</code>] <var>formula</var></dt><dd><p> Upload logs for a failed build of <var>formula</var> to a new Gist.</p>
+
+<p> <var>formula</var> is usually the name of the formula to install, but it can be specified
+ in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
+
+<p> If <code>--new-issue</code> is passed, automatically create a new issue in the appropriate
+ GitHub repository as well as creating the Gist.</p>
+
+<p> If no logs are found, an error message is presented.</p></dd>
 <dt class="flush"><code>home</code></dt><dd><p>Open Homebrew's own homepage in a browser.</p></dd>
 <dt><code>home</code> <var>formula</var></dt><dd><p>Open <var>formula</var>'s homepage in a browser.</p></dd>
 <dt><code>info</code> <var>formula</var></dt><dd><p>Display information about <var>formula</var>.</p></dd>
@@ -174,7 +183,7 @@ information on all installed formulae.</p>
 <dt><code>install</code> [<code>--debug</code>] [<code>--env=</code><var>std</var>|<var>super</var>] [<code>--ignore-dependencies</code>] [<code>--only-dependencies</code>] [<code>--cc=</code><var>compiler</var>] [<code>--build-from-source</code>|<code>--force-bottle</code>] [<code>--devel</code>|<code>--HEAD</code>] [<code>--keep-tmp</code>] <var>formula</var></dt><dd><p>Install <var>formula</var>.</p>
 
 <p><var>formula</var> is usually the name of the formula to install, but it can be specified
-several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
+in several different ways. See <a href="#SPECIFYING-FORMULAE" title="SPECIFYING FORMULAE" data-bare-link="true">SPECIFYING FORMULAE</a>.</p>
 
 <p>If <code>--debug</code> is passed and brewing fails, open an interactive debugging
 session with access to IRB or a shell inside the temporary build directory.</p>

share/man/man1/brew.1

@@ -211,6 +211,19 @@ If \fB\-\-build\-from\-source\fR is passed, download the source rather than a bo
 If \fB\-\-force\-bottle\fR is passed, download a bottle if it exists for the current version of OS X, even if it would not be used during installation\.
 .
 .TP
+\fBgist\-logs\fR [\fB\-\-new\-issue\fR|\fB\-n\fR] \fIformula\fR
+Upload logs for a failed build of \fIformula\fR to a new Gist\.
+.
+.IP
+\fIformula\fR is usually the name of the formula to install, but it can be specified in several different ways\. See \fISPECIFYING FORMULAE\fR\.
+.
+.IP
+If \fB\-\-new\-issue\fR is passed, automatically create a new issue in the appropriate GitHub repository as well as creating the Gist\.
+.
+.IP
+If no logs are found, an error message is presented\.
+.
+.TP
 \fBhome\fR
 Open Homebrew\'s own homepage in a browser\.
 .
@@ -244,7 +257,7 @@ See the docs for examples of using the JSON: \fIhttps://github\.com/Homebrew/bre
 Install \fIformula\fR\.
 .
 .IP
-\fIformula\fR is usually the name of the formula to install, but it can be specified several different ways\. See \fISPECIFYING FORMULAE\fR\.
+\fIformula\fR is usually the name of the formula to install, but it can be specified in several different ways\. See \fISPECIFYING FORMULAE\fR\.
 .
 .IP
 If \fB\-\-debug\fR is passed and brewing fails, open an interactive debugging session with access to IRB or a shell inside the temporary build directory\.