Documentation and cleanup

- Add Javadoc to new methods and classes
- Get rid of magic number

src/com/fsck/k9/controller/MessagingController.java

@@ -200,21 +200,56 @@ public class MessagingController implements Runnable {
     // Key is accountUuid:folderName:messageUid   ,   value is unimportant
     private ConcurrentHashMap<String, String> deletedUids = new ConcurrentHashMap<String, String>();
 
+    /**
+     * A holder class for pending notification data
+     *
+     * This class holds all pieces of information for constructing
+     * a notification with message preview.
+     */
     private static class NotificationData {
-        private int unreadBeforeNotification;
+        /** Number of unread messages before constructing the notification */
-        private LinkedList<Message> messages; // newest one first
+        int unreadBeforeNotification;
-        private LinkedList<MessageReference> droppedMessages; // newest one first
+        /**
+         * List of messages that should be used for the inbox-style overview.
+         * It's sorted from newest to oldest message.
+         * Don't modify this list directly, but use {@link addMessage} and
+         * {@link removeMatchingMessage} instead.
+         */
+        LinkedList<Message> messages;
+        /**
+         * List of references for messages that the user is still to be notified of,
+         * but which don't fit into the inbox style anymore. It's sorted from newest
+         * to oldest message.
+         */
+        LinkedList<MessageReference> droppedMessages;
 
-        // There's no point in storing more than 5 messages for the notification, as a single notification
+        /**
-        // can't display more than that anyway.
+         * Maximum number of messages to keep for the inbox-style overview.
+         * As of Jellybean, phone notifications show a maximum of 5 lines, while tablet
+         * notifications show 7 lines. To make sure no lines are silently dropped,
+         * we default to 5 lines.
+         */
         private final static int MAX_MESSAGES = 5;
 
+        /**
+         * Constructs a new data instance.
+         *
+         * @param unread Number of unread messages prior to instance construction
+         */
         public NotificationData(int unread) {
             unreadBeforeNotification = unread;
             droppedMessages = new LinkedList<MessageReference>();
             messages = new LinkedList<Message>();
         }
 
+        /**
+         * Adds a new message to the list of pending messages for this notification.
+         *
+         * The implementation will take care of keeping a meaningful amount of
+         * messages in {@link #messages}.
+         *
+         * @param m The new message to add.
+         */
         public void addMessage(Message m) {
             while (messages.size() >= MAX_MESSAGES) {
                 Message dropped = messages.removeLast();
@@ -223,6 +258,13 @@ public class MessagingController implements Runnable {
             messages.addFirst(m);
         }
 
+        /**
+         * Remove a certain message from the message list.
+         *
+         * @param context A context.
+         * @param ref Reference of the message to remove
+         * @return true if message was found and removed, false otherwise
+         */
         public boolean removeMatchingMessage(Context context, MessageReference ref) {
             for (MessageReference dropped : droppedMessages) {
                 if (dropped.equals(ref)) {
@@ -247,6 +289,11 @@ public class MessagingController implements Runnable {
             return false;
         }
 
+        /**
+         * Gets a list of references for all pending messages for the notification.
+         *
+         * @return Message reference list
+         */
         public ArrayList<MessageReference> getAllMessageRefs() {
             ArrayList<MessageReference> refs = new ArrayList<MessageReference>();
             for (Message m : messages) {
@@ -256,6 +303,11 @@ public class MessagingController implements Runnable {
             return refs;
         }
 
+        /**
+         * Gets the total number of messages the user is to be notified of.
+         *
+         * @return Amount of new messages the notification notifies for
+         */
         public int getNewMessageCount() {
             return messages.size() + droppedMessages.size();
         }
@@ -1771,7 +1823,7 @@ public class MessagingController implements Runnable {
 
                     // we're only interested in messages that need removing
                     if (!shouldBeNotifiedOf) {
-                        NotificationData data = getNotificationData(account, -1);
+                        NotificationData data = getNotificationData(account, null);
                         if (data != null) {
                             synchronized (data) {
                                 MessageReference ref = localMessage.makeMessageReference();
@@ -4461,12 +4513,23 @@ public class MessagingController implements Runnable {
         return true;
     }
 
-    private NotificationData getNotificationData(Account account, int previousUnreadMessageCount) {
+    /**
+     * Get the pending notification data for an account.
+     * See {@link NotificationData}.
+     *
+     * @param account The account to retrieve the pending data for
+     * @param previousUnreadMessageCount The number of currently pending messages, which will be used
+     *                                    if there's no pending data yet. If passed as null, a new instance
+     *                                    won't be created if currently not existent.
+     * @return A pending data instance, or null if one doesn't exist and
+     *          previousUnreadMessageCount was passed as null.
+     */
+    private NotificationData getNotificationData(Account account, Integer previousUnreadMessageCount) {
         NotificationData data;
 
         synchronized (notificationData) {
             data = notificationData.get(account.getAccountNumber());
-            if (data == null && previousUnreadMessageCount >= 0) {
+            if (data == null && previousUnreadMessageCount != null) {
                 data = new NotificationData(previousUnreadMessageCount);
                 notificationData.put(account.getAccountNumber(), data);
             }