Updated $signInWithPopup(), $signInWithRedirect(), and $signInWithCredential() docs (#896)

* Updated $signInWithPopup() and $signInWithRedirect() docs

* Responded to Kato's feedback on auth ref docs updates

Author: Jacob Wenger

docs/reference.md

@@ -686,11 +686,14 @@ for more details about email / password authentication.
 
 ### $signInWithPopup(provider)
 
-Authenticates the client using a popup-based OAuth flow. This function takes two
-arguments: the unique string identifying the OAuth provider to authenticate with (e.g. `"google"`).
+Authenticates the client using a popup-based OAuth flow. This function takes a single argument: a
+a string or provider object representing the OAuth provider to authenticate with. It returns a
+promise which is resolved or rejected when the authentication attempt is completed. If successful,
+the promise will be fulfilled with an object containing authentication data about the signed-in
+user. If unsuccessful, the promise will be rejected with an `Error` object.
 
-Optionally, you can pass a provider object (like `new firebase.auth.GoogleAuthProvider()`, etc)
-which can be configured with additional options.
+Valid values for the string version of the argument are `"facebook"`, `"github"`, `"google"`, and
+`"twitter"`:
 
 ```js
 $scope.authObj.$signInWithPopup("google").then(function(result) {
@@ -700,45 +703,100 @@ $scope.authObj.$signInWithPopup("google").then(function(result) {
 });
 ```
 
-This method returns a promise which is resolved or rejected when the authentication attempt is
-completed. If successful, the promise will be fulfilled with an object containing authentication
-data about the signed-in user. If unsuccessful, the promise will be rejected with an `Error` object.
+Alternatively, you can request certain scopes or custom parameters from the OAuth provider by
+passing a provider object (such as `new firebase.auth.GoogleAuthProvider()`) configured with
+additional options:
 
-Firebase currently supports Facebook, GitHub, Google, and Twitter authentication. Refer to
-[authentication documentation](https://firebase.google.com/docs/auth/)
-for information about configuring each provider.
+```js
+var provider = new firebase.auth.GoogleAuthProvider();
+provider.addScope("https://www.googleapis.com/auth/plus.login");
+provider.setCustomParameters({
+  login_hint: "[email protected]"
+});
+
+$scope.authObj.$signInWithPopup(provider).then(function(result) {
+  console.log("Signed in as:", result.user.uid);
+}).catch(function(error) {
+  console.error("Authentication failed:", error);
+});
+```
+
+Firebase currently supports [Facebook](https://firebase.google.com/docs/auth/web/facebook-login),
+[GitHub](https://firebase.google.com/docs/auth/web/github-auth),
+[Google](https://firebase.google.com/docs/auth/web/google-signin),
+and [Twitter](https://firebase.google.com/docs/auth/web/twitter-login) authentication. Refer to the
+linked documentation in the previous sentence for information about configuring each provider.
 
 ### $signInWithRedirect(provider[, options])
 
-Authenticates the client using a redirect-based OAuth flow. This function takes two
-arguments: the unique string identifying the OAuth provider to authenticate with (e.g. `"google"`).
+Authenticates the client using a redirect-based OAuth flow. This function takes a single argument: a
+string or provider object representing the OAuth provider to authenticate with. It returns a
+rejected promise with an `Error` object if the authentication attempt fails. Upon successful
+authentication, the browser will be redirected as part of the OAuth authentication flow. As such,
+the returned promise will never be fulfilled. Instead, you should use the `$onAuthStateChanged()`
+method to detect when the authentication has been successfully completed.
 
-Optionally, you can pass a provider object (like `new firebase.auth().GoogleProvider()`, etc)
-which can be configured with additional options.
+Valid values for the string version of the argument are `"facebook"`, `"github"`, `"google"`, and
+`"twitter"`:
 
 ```js
 $scope.authObj.$signInWithRedirect("google").then(function() {
   // Never called because of page redirect
+  // Instead, use $onAuthStateChanged() to detect successful authentication
 }).catch(function(error) {
   console.error("Authentication failed:", error);
 });
 ```
 
-This method returns a rejected promise with an `Error` object if the authentication attempt fails.
-Upon successful authentication, the browser will be redirected as part of the OAuth authentication
-flow. As such, the returned promise will never be fulfilled. Instead, you should use the `$onAuthStateChanged()`
-method to detect when the authentication has been successfully completed.
+Alternatively, you can request certain scopes or custom parameters from the OAuth provider by
+passing a provider object (such as `new firebase.auth.GoogleAuthProvider()`) configured with
+additional options:
+
+```js
+var provider = new firebase.auth.GoogleAuthProvider();
+provider.addScope("https://www.googleapis.com/auth/plus.login");
+provider.setCustomParameters({
+  login_hint: "[email protected]"
+});
 
-Firebase currently supports Facebook, GitHub, Google, and Twitter authentication. Refer to
-[authentication documentation](https://firebase.google.com/docs/auth/)
-for information about configuring each provider.
+$scope.authObj.$signInWithRedirect(provider).then(function(result) {
+  // Never called because of page redirect
+  // Instead, use $onAuthStateChanged() to detect successful authentication
+}).catch(function(error) {
+  console.error("Authentication failed:", error);
+});
+```
+
+Firebase currently supports [Facebook](https://firebase.google.com/docs/auth/web/facebook-login),
+[GitHub](https://firebase.google.com/docs/auth/web/github-auth),
+[Google](https://firebase.google.com/docs/auth/web/google-signin),
+and [Twitter](https://firebase.google.com/docs/auth/web/twitter-login) authentication. Refer to the
+linked documentation in the previous sentence for information about configuring each provider.
 
 ### $signInWithCredential(credential)
 
-Authenticates the client using a credential (potentially created from OAuth Tokens). This function takes one
-arguments: the credential object. This may be obtained from individual auth providers under `firebase.auth()`;
+Authenticates the client using a credential. This function takes a single argument: the credential
+object. Credential objects are created from a provider-specific set of user data, such as their
+email / password combination or an OAuth access token.
 
 ```js
+// Email / password authentication with credential
+var credential = firebase.auth.EmailAuthProvider.credential(email, password);
+
+$scope.authObj.$signInWithCredential(credential).then(function(firebaseUser) {
+  console.log("Signed in as:", firebaseUser.uid);
+}).catch(function(error) {
+  console.error("Authentication failed:", error);
+});
+```
+
+```js
+// Facebook authentication with credential
+var credential = firebase.auth.FacebookAuthProvider.credential(
+  // `event` come from the Facebook SDK's auth.authResponseChange() callback
+  event.authResponse.accessToken
+);
+
 $scope.authObj.$signInWithCredential(credential).then(function(firebaseUser) {
   console.log("Signed in as:", firebaseUser.uid);
 }).catch(function(error) {
@@ -750,9 +808,14 @@ This method returns a promise which is resolved or rejected when the authenticat
 completed. If successful, the promise will be fulfilled with an object containing authentication
 data about the signed-in user. If unsuccessful, the promise will be rejected with an `Error` object.
 
-Firebase currently supports Facebook, GitHub, Google, and Twitter authentication. Refer to
-[authentication documentation](https://firebase.google.com/docs/auth/)
-for information about configuring each provider.
+Firebase currently supports `$signInWithCredential()` for the
+[email / password](https://firebase.google.com/docs/reference/node/firebase.auth.EmailAuthProvider#.credential),
+[Facebook](https://firebase.google.com/docs/reference/node/firebase.auth.FacebookAuthProvider#.credential),
+[GitHub](https://firebase.google.com/docs/reference/node/firebase.auth.GithubAuthProvider#.credential),
+[Google](https://firebase.google.com/docs/reference/node/firebase.auth.GoogleAuthProvider#.credential),
+and [Twitter](https://firebase.google.com/docs/reference/node/firebase.auth.TwitterAuthProvider#.credential)
+authentication providers. Refer to the linked documentation in the previous sentence for information
+about creating a credential for each provider.
 
 ### $getAuth()
 
@@ -897,8 +960,8 @@ section of our AngularFire guide for more information and a full example.
 ### $requireSignIn(requireEmailVerification)
 
 Helper method which returns a promise fulfilled with the current authentication state if the user
-is authenticated and, if specified, has a verified email address, but otherwise rejects the promise. 
-This is intended to be used in the `resolve()` method of Angular routers to prevented unauthenticated 
+is authenticated and, if specified, has a verified email address, but otherwise rejects the promise.
+This is intended to be used in the `resolve()` method of Angular routers to prevent unauthenticated
 users from seeing authenticated pages momentarily during page load. See the
 ["Using Authentication with Routers"](/docs/guide/user-auth.md#authenticating-with-routers)
 section of our AngularFire guide for more information and a full example.