docs(authentication): Adds API documentation for AngularFireAuth methods

Added AngulaFireAuth API's as per issue #93.
Fixes a type in logout code; update to match auth guide

This closes #93.

Author: mukesh51

docs/api-reference.md

@@ -121,17 +121,22 @@ bootstrap(App, [
 ]);
 ```
 
-### FirebaseAuth
+### AngularFireAuth
 
-Injectable service for managing authentication state.
+Type: `class`
+
+Injectable service for managing authentication state. Extends rxjs `ReplaySubject`, which represents an object that is both an observable sequence as well as an observer.
 
 #### Logging In
 To log in a user, call the `login` method on an instance of `FirebaseAuth` class. The method has
 the following two signatures:
 
 ```ts
-login(config?: AuthConfiguration): Promise<FirebaseAuthState>;
-login(credentials: AuthCredentials, config?: AuthConfiguration): Promise<FirebaseAuthState>;
+login(config?: AuthConfiguration): firebase.Promise<FirebaseAuthState>;
+login(credentials?: EmailPasswordCredentials | 
+    firebase.auth.AuthCredential | string): firebase.Promise<FirebaseAuthState>;
+login(credentials: EmailPasswordCredentials | 
+    firebase.auth.AuthCredential | string, config?: AuthConfiguration): firebase.Promise<FirebaseAuthState>
 ```
 
 The signature that is used depends on which AuthMethod you chose to use to login.
@@ -189,6 +194,61 @@ export class MyApp {
 }
 ```
 
+The AuthConfiguration Object has the following signature
+ 
+ ```ts
+ export interface AuthConfiguration {
+ 		method?: AuthMethods;
+ 		provider?: AuthProviders;
+ 		remember?: string;
+ 		scope?: string[];
+   }
+ ```
+ 
+ * The AuthMethods and AuthProviders are enums, defining values for Methods and Providers respectively.  
+  See [Facebook-Login](https://firebase.google.com/docs/auth/web/facebook-login) and [Google-Signin](https://firebase.google.com/docs/auth/web/google-signin) for more information.
+ 
+ Usage:
+ 
+ ```ts
+ ....
+ signInWithFacebook(): Promise<FirebaseAuthState> {
+ 	     return this.auth$.login({
+ 		 provider: AuthProviders.Facebook,
+ 		 method: AuthMethods.Popup,
+ 	     });
+     }
+ ....
+ ```
+ 
+
+```ts
+ ....
+ signInWithGoogle(): Promise<FirebaseAuthState> {
+     	     return this.auth$.login({
+     		 provider: AuthProviders.Google,
+     		 method: AuthMethods.Redirect,
+     	     });
+ ....
+ ```
+ 
+
+`login(credentials?: EmailPasswordCredentials | firebase.auth.AuthCredential | string): firebase.Promise<FirebaseAuthState>` :
+ 
+ Takes one of the three arguments as input. The `EmailPasswordCredentials` object is same, as mentioned in createUser method. The login method can also take a [firebase.auth.AuthCredential](https://firebase.google.com/docs/reference/js/firebase.auth.AuthCredential) object as mentioned here.
+ 
+ Usage:
+ 
+ ```ts
+ ....
+     signInWithEmail(): Promise<FirebaseAuthState> {
+             return this.auth$.login({
+                 email: "[email protected]",
+                 password: 'yourPassword'
+         });
+ ....
+ ```    
+
 #### Subscribing to Authentication State
 
 Type: `class FirebaseAuth extends ReplaySubject<FirebaseAuthState>`
@@ -226,6 +286,64 @@ class App {
 
 ```
 
+
+`getAuth(): FirebaseAuthState` : Returns the client's current Authentication State. The FirebaseAuthState is an interface with following  signature 
+
+```ts
+export interface FirebaseAuthState {
+  uid: string;
+  provider: AuthProviders;
+  auth: firebase.User;
+  expires?: number;
+  github?: firebase.UserInfo;
+  google?: firebase.UserInfo;
+  twitter?: firebase.UserInfo;
+  facebook?: firebase.UserInfo;
+  anonymous?: boolean;
+}
+```
+
+Sample Usage:
+
+```ts
+constructor(public auth: FirebaseAuth) {
+        this.authState = auth.getAuth();
+        auth.subscribe((state: FirebaseAuthState) => {
+            this.authState = state;          
+        });        
+    }
+
+    get authenticated(): boolean {        
+        return this.authState !== null;
+    }
+```
+
+`logout(): void`: Deletes the authentication token issued by Firebase and signs user out. See [Auth.signOut()](https://firebase.google.com/docs/reference/js/firebase.auth.Auth#signOut) for more information.
+
+*It is worth noting that logout() is an asynchronous operation. There is an open bug against the Firebase SDK to make this return a promise.*
+
+Sample Usage:
+
+```ts
+	signOut(): {
+		this.af.auth.logout();
+	}
+```
+
+`createUser(credentials: EmailPasswordCredentials): firebase.Promise<FirebaseAuthState>` : Creates a new user with email/password provided. Returns a promise filled with FirebaseAuthState, which contains the uid of the created user.
+
+The credentials object is an object containing email and password of the user to be created. See [createUserWithEmailAndPassword](https://firebase.google.com/docs/reference/js/firebase.auth.Auth#createUserWithEmailAndPassword) for more information.
+
+```ts
+  createNewUser(properties:Object): Promise<FirebaseAuthState> {
+        return this.auth.createUser({
+            email: '[email protected]',
+            password: 'uniquePassword'
+        })
+    }
+```
+
+
 ### FirebaseListObservable
 
 Subclass of rxjs `Observable` which also has methods for updating
@@ -294,3 +412,4 @@ This is the equivalent of the Firebase SDK's
 If no `item` argument is provided, it removes all elements from the list.
  This is the equivalent of the Firebase SDK's
  [remove() method](https://firebase.google.com/docs/reference/js/firebase.database.Reference#remove).
+