Add documentation.

Author: Sam1301

app/src/main/java/com/zulip/android/ZulipApp.java

@@ -243,8 +243,12 @@ public Message deserialize(JsonElement json, Type typeOfT, JsonDeserializationCo
                         } else {
                             Message.ZulipDirectMessage msg = naiveGson.fromJson(json, Message.ZulipDirectMessage.class);
                             if (msg.getDisplayRecipient() != null) {
+                                // set the correct person id for message recipients
                                 List<Person> people = msg.getDisplayRecipient();
                                 for (Person person : people) {
+                                    // this is needed as the json field name for person id is
+                                    // "user_id" in realm configuration response and "id" in
+                                    // GET v1/messages response.
                                     person.setId(person.getRecipientId());
                                 }
 

app/src/main/java/com/zulip/android/models/Message.java

@@ -430,6 +430,10 @@ public void setRecipients(Person[] list) {
         this.recipientsCache = list;
 
         try {
+            /* Since person ids were auto-generated before, we needed to get the person object "to"
+            and "from" from the database to have the correct id. After shifting to server
+            generated ids, the list passed already has person objects "to"(list[0]) and
+            "from"(list[1]) having correct ids. */
             Person to = list[0];
 
             if (list.length == 1) {

app/src/main/java/com/zulip/android/models/Person.java

@@ -62,6 +62,9 @@ public class Person {
     @SerializedName("is_mirror_dummy")
     private boolean isMirrorDummy;
 
+    /**
+     * used to get person id in case of {@link Message.ZulipDirectMessage}
+     */
     @SerializedName("id")
     private int recipientId;
 
@@ -115,6 +118,19 @@ public static Person getByEmail(Dao<Person, ?> dao, String email) {
     }
 
     @SuppressWarnings("WeakerAccess")
+    /**
+     * Returns person object {@link Person} from the database if exists or newly created object using
+     * the passed parameters.
+     * Note: always call this method with valid Person id {@link Person#id} passed as argument.
+     *
+     * @param app Zulip god object {@link ZulipApp}
+     * @param email person email {@link Person#email}
+     * @param name person name {@link Person#name}
+     * @param avatarURL person avatar url {@link Person#avatarURL}
+     * @param personId person id {@link Person#id}
+     * @param personCache person cache used ofr faster fetching of results
+     * @return {@link Person} object
+     */
     public static Person getOrUpdate(ZulipApp app, String email, String name,
                                      String avatarURL, int personId, Map<String, Person> personCache) {
 
@@ -133,6 +149,9 @@ public static Person getOrUpdate(ZulipApp app, String email, String name,
 
         if (person == null) {
             person = new Person(name, email, avatarURL);
+
+            // use the person id passed to generate person skeleton object which is consistent
+            // with server id.
             person.setId(personId);
             app.getDao(Person.class).create(person);
         } else {
@@ -152,6 +171,18 @@ public static Person getOrUpdate(ZulipApp app, String email, String name,
         return person;
     }
 
+    /**
+     * This function is used to call {@link Person#getOrUpdate(ZulipApp, String, String, String, int, Map)}
+     * with no cache.
+     * Note: always call this method with valid Person id {@link Person#id} passed as argument.
+     *
+     * @param app Zulip god object {@link ZulipApp}
+     * @param email person email {@link Person#email}
+     * @param name person name {@link Person#name}
+     * @param avatarURL person avatar url {@link Person#avatarURL}
+     * @param personId person id {@link Person#id}
+     * @return {@link Person} object
+     * */
     public static Person getOrUpdate(ZulipApp app, String email, String name,
                                      String avatarURL, int personId) {
         return getOrUpdate(app, email, name, avatarURL, personId, null);

app/src/main/java/com/zulip/android/networking/AsyncGetEvents.java

@@ -190,7 +190,8 @@ public Void call() throws Exception {
                         person.setActive(true);
                         try {
                             if (person.getEmail().equalsIgnoreCase(app.getYou().getEmail())) {
-                                // change the id
+                                // change the id of "you" to correct server id after login
+                                // this statement also updates app.getYou with updated id
                                 personDao.updateId(app.getYou(), person.getId());
                             }
                             personDao.createOrUpdate(person);

app/src/main/java/com/zulip/android/util/CustomHtmlToSpannedConverter.java

@@ -242,7 +242,7 @@ private static void startSpan(SpannableStringBuilder text, Attributes attributes
             int id = Integer.parseInt(stringId);
             email = Person.getById(ZulipApp.get(), id).getEmail();
         } else {
-            // for historical messages
+            // for historical messages, revert to use of this attribute
             email = attributes.getValue("data-user-email");
         }