The beginnings of some decent API documentation.

Also, tweak `.yardopts` to better fix our internal style.

Closes Homebrew/homebrew#34785.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>

`brew-gem`'s link is 404.
`brew-pip` has reached EOL.
Thus I updates the link of `brew-gem`, and remove descriptions
about `brew-pip`.

Thanks @DomT4 for pointing out brew-gem's new home.

Closes Homebrew/homebrew#34569.

Signed-off-by: Jack Nagel <jacknagel@gmail.com>

The downloader is instantiated on-demand, so we no longer need the lazy
initialization here.

We need to limit the interface that is exposed to the downloader in
order to make future changes easier.

This will be important for work on new features, such as selecting
a mirror from the command line.

In the future, the existing Resource class will probably be split into
multiple classes.

Fixes Homebrew/homebrew#34713.

This reverts commit e4461afd36f04b1cd3cf56ec0636202150ce0570.

Since bsdmake is always specified as a dependency, our xcrun wrapper
will always be able to find it, so we can get rid of this wrapper.

How-to-use-keg-only-outside-of-brew:
* A new piece of documentation detailing how to deal with using
keg_only formula outside of Brew itself. We’ve had a lot of questions
and issues about this recently, and the solutions aren’t as easy and
explicit to find elsewhere, so detailing it here may help reduce some
of the questions we’ve seen recently.
* I possibly whinged too much in the second section. I’m open to
criticism and being called whiny.
* Details flags, prepending the $PATH, and dealing with pkg-config.

Closes Homebrew/homebrew#34608.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>

Fixes Homebrew/homebrew#33437.

Bumps to the latest Xcode 6.1.1.

Closes Homebrew/homebrew#34632.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>