refactor: document public user functions, add nullability annotations

sdk/src/androidTest/java/com/bugsnag/android/UserTest.java

@@ -0,0 +1,62 @@
+package com.bugsnag.android;
+
+import static com.bugsnag.android.BugsnagTestUtils.streamableToJson;
+import static org.junit.Assert.assertEquals;
+
+import android.support.test.filters.SmallTest;
+import android.support.test.runner.AndroidJUnit4;
+
+import org.json.JSONException;
+import org.json.JSONObject;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import java.io.IOException;
+
+@RunWith(AndroidJUnit4.class)
+@SmallTest
+public class UserTest {
+
+    private User user;
+
+    @Before
+    public void setUp() throws Exception {
+        user = new User("123", "bob@example.com", "bob smith");
+    }
+
+    @Test
+    public void testUserDefaults() {
+        assertEquals("123", user.getId());
+        assertEquals("bob smith", user.getName());
+        assertEquals("bob@example.com", user.getEmail());
+    }
+
+    @Test
+    public void testUserCopy() {
+        user = new User(user);
+        assertEquals("123", user.getId());
+        assertEquals("bob smith", user.getName());
+        assertEquals("bob@example.com", user.getEmail());
+    }
+
+    @Test
+    public void testUserOverride() {
+        user.setId("4fd");
+        user.setName("jane");
+        user.setEmail("jane@example.com");
+        assertEquals("4fd", user.getId());
+        assertEquals("jane", user.getName());
+        assertEquals("jane@example.com", user.getEmail());
+    }
+
+    @Test
+    public void testJsonSerialisation() throws JSONException, IOException {
+        JSONObject userJson = streamableToJson(user);
+        assertEquals(3, userJson.length());
+        assertEquals("123", userJson.get("id"));
+        assertEquals("bob smith", userJson.get("name"));
+        assertEquals("bob@example.com", userJson.get("email"));
+    }
+
+}

sdk/src/main/java/com/bugsnag/android/User.java

@@ -1,21 +1,28 @@
 package com.bugsnag.android;
 
 import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
 
 import java.io.IOException;
 
 /**
  * Information about the current user of your application.
  */
-class User implements JsonStream.Streamable {
+public class User implements JsonStream.Streamable {
+
+    @Nullable
     private String id;
+
+    @Nullable
     private String email;
+
+    @Nullable
     private String name;
 
     User() {
     }
 
-    User(String id, String email, String name) {
+    User(@Nullable String id, @Nullable String email, @Nullable String name) {
         this.id = id;
         this.email = email;
         this.name = name;
@@ -36,27 +43,54 @@ public void toStream(@NonNull JsonStream writer) throws IOException {
         writer.endObject();
     }
 
+    /**
+     * @return the user ID, by default a UUID generated on installation
+     */
+    @Nullable
     public String getId() {
         return id;
     }
 
-    public void setId(String id) {
+    /**
+     * Overrides the default user ID
+     *
+     * @param id the new ID
+     */
+    public void setId(@Nullable String id) {
         this.id = id;
     }
 
+    /**
+     * @return the user's email, if available
+     */
+    @Nullable
     public String getEmail() {
         return email;
     }
 
-    public void setEmail(String email) {
+    /**
+     * Sets the user's email
+     *
+     * @param email the user email
+     */
+    public void setEmail(@Nullable String email) {
         this.email = email;
     }
 
+    /**
+     * @return the user's name, if available
+     */
+    @Nullable
     public String getName() {
         return name;
     }
 
-    public void setName(String name) {
+    /**
+     * Sets the user's name
+     *
+     * @param name the user name
+     */
+    public void setName(@Nullable String name) {
         this.name = name;
     }
 }