Add documentation of "Who am I" API

Ref. SkygearIO/skygear-server#111

content/android/user-auth.md

@@ -105,8 +105,28 @@ Log.i("Skygear User", "User ID: " + currentUser.userId);
 Log.i("Skygear User", "Username: " + currentUser.username);
 ```
 
+Please be reminded that the `currentUser` object only retrieved when user
+login / signup Skygear.
+
+To get the latest information (e.g. roles, emails, etc.) of the current user,
+you can ask "Who am I" to Skygear:
+
+```java
+skygear.whoami(new AuthResponseHandler() {
+    @Override
+    public void onAuthSuccess(User user) {
+        Log.i("Skygear User", "I am " + user.getUsername());
+    }
+
+    @Override
+    public void onAuthFail(String reason) {
+        // Error handling...
+    }
+});
+```
+
 <a name="social-login"></a>
 ## Social Login (Facebook, Twitter, etc)
 
 <a name="user-profile"></a>
-## User Profile
+## User Profile

content/ios/user.md

@@ -8,7 +8,7 @@ The first thing you want a user to do is to sign up. The following code illustra
 ```obj-c
 [container signupWithUsername:@"john.doe"
                      password:@"verysecurepasswd"
-completionHandler:^(SKYUser *user, NSError *error) {
+            completionHandler:^(SKYUser *user, NSError *error) {
     if (error) {
         NSLog(@"error signing up user: %@", error);
         return;
@@ -48,7 +48,7 @@ You can use `loginWithUsername:password:` to let users log in to their accounts
 ```obj-c
 [container loginWithUsername:@"john.doe"
                     password:@"verysecurepasswd"
-completionHandler:^(SKYUserRecordID *user, NSError *error) {
+           completionHandler:^(SKYUserRecordID *user, NSError *error) {
     if (error) {
         NSLog(@"error loggin user in: %@", error);
         return;
@@ -117,6 +117,19 @@ if (container.currentUserRecordID) {
 }
 ```
 
+You can get the latest information (e.g. roles, emails, etc.) of the current
+user by asking "Who am I" to Skygear:
+
+```obj-c
+[[SKYContainer defaultContainer] getWhoAmIWithCompletionHandler:^(SKYUser *user, NSError *error) {
+    if (error) {
+        // Error handling...
+    } else {
+        NSLog(@"Oh. I am %@.", user.username);
+    }
+}];
+```
+
 ### Looking up users by email
 
 Skygear provide a user discovery method by email. Everyone has access to this method without even having to be logged in.
@@ -151,16 +164,16 @@ user profile is public and thus visible to any user.
 
 ```obj-c
 SKYDatabase *publicDB = [[SKYContainer defaultContainer] publicCloudDatabase];
-    NSPredicate *predicate = [NSPredicate predicateWithFormat:@"_id ==[c] %@", [container currentUserRecordID]];
-    SKYQuery *query = [SKYQuery queryWithRecordType:@"user" predicate:predicate];
-    
-    [publicDB performQuery:query completionHandler:^(NSArray *results, NSError *error) {
-        if (error) {
-            NSLog(@"error quering user profile: %@", error);
-            return;
-        }
-        
-        NSLog(@"query successful");
-        // do something else
-    }];
-```
+NSPredicate *predicate = [NSPredicate predicateWithFormat:@"_id ==[c] %@", [container currentUserRecordID]];
+SKYQuery *query = [SKYQuery queryWithRecordType:@"user" predicate:predicate];
+
+[publicDB performQuery:query completionHandler:^(NSArray *results, NSError *error) {
+    if (error) {
+        NSLog(@"error quering user profile: %@", error);
+        return;
+    }
+
+    NSLog(@"query successful");
+    // do something else
+}];
+```

content/js/users.md

@@ -82,6 +82,21 @@ If there is an authenticated user, it will give you a user object like this:
 }
 ```
 
+Please be reminded that the `currentUser` object only retrieved when user
+login / signup Skygear.
+
+To get the latest information (e.g. roles, emails, etc.) of the current user,
+you can ask "Who am I" to Skygear:
+
+``` javascript
+skygear.whoami().then((user) => {
+    console.log(`Oh. I am ${user.username}.`);
+}, (err) => {
+    // Error handling...
+})
+
+```
+
 ### Observing user changes
 
 The preferred way for your app to handle any logged-in user change is to
@@ -108,6 +123,7 @@ const handler = skygear.onUserChanged(function (user) {
 handler.cancel(); // The callback is cancelable
 ```
 
+
 <a name="signup-login-logout"></a>
 ## Signing up / Logging in / Logging out
 
@@ -225,7 +241,7 @@ skygear.logout().then(() => {
 
 ### Changing the email of a user
 
-To change a user's email, you can use the `skygear.saveUser` method by 
+To change a user's email, you can use the `skygear.saveUser` method by
 providing the user ID and the new email.
 Every user can change his/her own email while
 only users with the admin role can change the emails of other users.
@@ -314,7 +330,7 @@ auth provider, along with the relevant auth data (an object) necessary for
 the authentication, such as the access token obtained from Facebook.
 
 For example, if you have implemented a Facebook auth provider under the name
-`com.facebook` using 
+`com.facebook` using
 `@skygear.provides('auth', 'com.facebook')` in the cloud code,
 you can log a user in by: