The Formula API is no longer work-in-progress.

Feature it a bit more prominently in the documentation as a result. Closes #45374. Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>
Homebrew · Oct 27, 2015 · 2b5d884 · 2b5d884
1 parent 0cad93e
commit 2b5d884
Show file tree

Hide file tree

Showing 7 changed files with 15 additions and 10 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -13,6 +13,10 @@ Please report security issues to security@brew.sh.
 Please read:
 
 * [Code of Conduct](https://github.com/Homebrew/homebrew/blob/master/CODEOFCONDUCT.md#code-of-conduct)
+
+To contribute code please read:
+
+* [Formula API](http://www.rubydoc.info/github/Homebrew/homebrew/master/frames)
 * [Formula Cookbook](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md#formula-cookbook)
 * [Acceptable Formulae](https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Acceptable-Formulae.md#acceptable-formulae)
 * [Ruby Style Guide](https://github.com/styleguide/ruby)

diff --git a/Library/Homebrew/README.md b/Library/Homebrew/README.md
@@ -1,5 +1,5 @@
 # Homebrew's Formula API
-This is the (partially) documented public API for Homebrew. It's currently a work in progress. Sorry about that!
+This is the (partially) documented public API for Homebrew.
 
 The main class you should look at is the {Formula} class (and classes linked from there). That's the class that's used to create Homebrew formulae (i.e. package descriptions). Assume anything else you stumble upon is private.
 

diff --git a/Library/Homebrew/cmd/create.rb b/Library/Homebrew/cmd/create.rb
@@ -118,7 +118,7 @@ def generate!
 
   def template; <<-EOS.undent
     # Documentation: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Formula-Cookbook.md
-    #                http://www.rubydoc.info/github/Homebrew/homebrew/master/frames
+    #                http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula
     # PLEASE REMOVE ALL GENERATED COMMENTS BEFORE SUBMITTING YOUR PULL REQUEST!
 
     class #{Formulary.class_s(name)} < Formula

diff --git a/Library/Homebrew/manpages/brew.1.md b/Library/Homebrew/manpages/brew.1.md
@@ -90,9 +90,9 @@ Note that these flags should only appear after a command.
     Generate a formula for the downloadable file at <URL> and open it in the editor.
     Homebrew will attempt to automatically derive the formula name
     and version, but if it fails, you'll have to make your own template. The wget
-    formula serves as a simple example. For a complete cheat-sheet, have a look at
+    formula serves as a simple example. For the complete API have a look at
 
-    <http://www.rubydoc.info/github/Homebrew/homebrew/master/frames>
+    <http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula>
 
     If `--autotools` is passed, create a basic template for an Autotools-style build.
     If `--cmake` is passed, create a basic template for a CMake-style build.

diff --git a/share/doc/homebrew/Formula-Cookbook.md b/share/doc/homebrew/Formula-Cookbook.md
@@ -3,6 +3,9 @@ Making a formula is easy. Just `brew create URL` and then `brew install $FORMULA
 
 We want your formula to be awesome, and the cookbook will tell you how.
 
+## API documentation
+Some people find it easier to jump straight into API documentation rather than a walkthrough. If you're one of these check out the [Formula API](http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula) which shows all the stuff you can use in a Homebrew Formula.
+
 ## Terminology - Homebrew speak
 
 <table>
@@ -82,8 +85,6 @@ Formulae aren’t that complicated. [etl](https://github.com/Homebrew/homebrew/b
 
 And then [Git](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/git.rb) and [flac](https://github.com/Homebrew/homebrew/tree/master/Library/Formula/flac.rb) show more advanced functionality.
 
-Refer to the [Formula class API documentation](http://www.rubydoc.info/github/Homebrew/homebrew/master/frames) which shows all the stuff you can use in a Formula.
-
 ## Grab the URL
 
 All you need to make a formula is a URL to the tarball.

diff --git a/share/doc/homebrew/brew.1.html b/share/doc/homebrew/brew.1.html
@@ -82,9 +82,9 @@ <h2 id="COMMANDS">COMMANDS</h2>
 Generate a formula for the downloadable file at <var>URL</var> and open it in the editor.
 Homebrew will attempt to automatically derive the formula name
 and version, but if it fails, you'll have to make your own template. The wget
-formula serves as a simple example. For a complete cheat-sheet, have a look at</p>
+formula serves as a simple example. For the complete API have a look at</p>
 
-<p><a href="http://www.rubydoc.info/github/Homebrew/homebrew/master/frames" data-bare-link="true">http://www.rubydoc.info/github/Homebrew/homebrew/master/frames</a></p>
+<p><a href="http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula" data-bare-link="true">http://www.rubydoc.info/github/Homebrew/homebrew/master/Formula</a></p>
 
 <p>If <code>--autotools</code> is passed, create a basic template for an Autotools-style build.
 If <code>--cmake</code> is passed, create a basic template for a CMake-style build.</p>

diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
@@ -89,10 +89,10 @@ If \fB\-\-quiet\fR is passed, list only the names of commands without the header
 \fBconfig\fR: Show Homebrew and system configuration useful for debugging\. If you file a bug report, you will likely be asked for this information if you do not provide it\.
 .
 .IP "\(bu" 4
-\fBcreate <URL> [\-\-autotools|\-\-cmake] [\-\-no\-fetch] [\-\-set\-name <name>] [\-\-set\-version <version>]\fR: Generate a formula for the downloadable file at \fIURL\fR and open it in the editor\. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you\'ll have to make your own template\. The wget formula serves as a simple example\. For a complete cheat\-sheet, have a look at
+\fBcreate <URL> [\-\-autotools|\-\-cmake] [\-\-no\-fetch] [\-\-set\-name <name>] [\-\-set\-version <version>]\fR: Generate a formula for the downloadable file at \fIURL\fR and open it in the editor\. Homebrew will attempt to automatically derive the formula name and version, but if it fails, you\'ll have to make your own template\. The wget formula serves as a simple example\. For the complete API have a look at
 .
 .IP
-\fIhttp://www\.rubydoc\.info/github/Homebrew/homebrew/master/frames\fR
+\fIhttp://www\.rubydoc\.info/github/Homebrew/homebrew/master/Formula\fR
 .
 .IP
 If \fB\-\-autotools\fR is passed, create a basic template for an Autotools\-style build\. If \fB\-\-cmake\fR is passed, create a basic template for a CMake\-style build\.