add/fix/de-duplicate comments

src/driver.h

@@ -73,10 +73,13 @@ typedef struct message {
 	char tuid[TUIDL];
 } message_t;
 
-/* For opts, both in store and driver_t->select() */
+// For driver_t->prepare_load_box(), which may amend the passed flags.
-#define OPEN_OLD        (1<<0)
+// The drivers don't use the first two, but may set them if loading the
-#define OPEN_NEW        (1<<1)
+// particular range is required to handle some other flag; note that these
-#define OPEN_FLAGS      (1<<2)
+// ranges may overlap.
+#define OPEN_OLD        (1<<0)  // Paired messages *in* this store.
+#define OPEN_NEW        (1<<1)  // Messages (possibly) not yet propagated *from* this store.
+#define OPEN_FLAGS      (1<<2)  // Note that fetch_msg() gets the flags regardless.
 #define OPEN_OLD_SIZE   (1<<3)
 #define OPEN_NEW_SIZE   (1<<4)
 #define OPEN_EXPUNGE    (1<<5)
@@ -234,17 +237,17 @@ struct driver {
 	 * a pre-fetched one (in which case the in-memory representation is updated),
 	 * or it may be identifed by UID only. The operation may be delayed until commit()
 	 * is called. */
-	void (*set_msg_flags)( store_t *ctx, message_t *msg, uint uid, int add, int del, /* msg can be null, therefore uid as a fallback */
+	void (*set_msg_flags)( store_t *ctx, message_t *msg, uint uid, int add, int del,
 	                       void (*cb)( int sts, void *aux ), void *aux );
 
 	/* Move the given message from the current mailbox to the trash folder.
 	 * This may expunge the original message immediately, but it needn't to. */
-	void (*trash_msg)( store_t *ctx, message_t *msg, /* This may expunge the original message immediately, but it needn't to */
+	void (*trash_msg)( store_t *ctx, message_t *msg,
 	                   void (*cb)( int sts, void *aux ), void *aux );
 
 	/* Expunge deleted messages from the current mailbox and close it.
 	 * There is no need to explicitly close a mailbox if no expunge is needed. */
-	void (*close_box)( store_t *ctx, /* IMAP-style: expunge inclusive */
+	void (*close_box)( store_t *ctx,
 	                   void (*cb)( int sts, void *aux ), void *aux );
 
 	/* Cancel queued commands which are not in flight yet; they will have their

src/drv_imap.c

@@ -3099,6 +3099,7 @@ imap_find_new_msgs_p2( imap_store_t *ctx, imap_cmd_t *gcmd, int response )
 		return;
 	}
 
+	// We appended messages, so we need to re-query UIDNEXT.
 	ctx->uidnext = 0;
 
 	INIT_IMAP_CMD(imap_cmd_find_new_t, cmd, cmdp->callback, cmdp->callback_aux)

src/run-tests.pl

@@ -578,6 +578,7 @@ sub ckchan($$)
 	return $rslt;
 }
 
+# $boxname, $maxuid, @msgs
 sub printbox($$@)
 {
 	my ($bn, $mu, @ms) = @_;

src/sync.c

@@ -128,7 +128,7 @@ make_flags( uchar flags, char *buf )
 	return d;
 }
 
-// These is the (mostly) persistent status of the sync record.
+// This is the (mostly) persistent status of the sync record.
 // Most of these bits are actually mutually exclusive. It is a
 // bitfield to allow for easy testing for multiple states.
 #define S_EXPIRE       (1<<0)  // the entry is being expired (near side message removal scheduled)
@@ -757,7 +757,7 @@ load_state( sync_vars_t *svars )
 			}
 			if (ll == 1)
 				goto gothdr;
-			if (line == 1 && isdigit( buf[0] )) {
+			if (line == 1 && isdigit( buf[0] )) {  // Pre-1.1 legacy
 				if (sscanf( buf, "%63s %63s", buf1, buf2 ) != 2 ||
 				    sscanf( buf1, "%u:%u", &svars->uidval[F], &svars->maxuid[F] ) < 2 ||
 				    sscanf( buf2, "%u:%u:%u", &svars->uidval[N], &maxxnuid, &svars->maxuid[N] ) < 3) {
@@ -781,7 +781,7 @@ load_state( sync_vars_t *svars )
 				svars->maxuid[N] = uid;
 			else if (!strcmp( buf1, "MaxExpiredFarUid" ) || !strcmp( buf1, "MaxExpiredMasterUid" ) /* Pre-1.4 legacy */)
 				svars->maxxfuid = uid;
-			else if (!strcmp( buf1, "MaxExpiredSlaveUid" ))  // Legacy
+			else if (!strcmp( buf1, "MaxExpiredSlaveUid" ))  // Pre-1.3 legacy
 				maxxnuid = uid;
 			else {
 				error( "Error: unrecognized sync state header entry at %s:%d\n", svars->dname, line );
@@ -1263,7 +1263,7 @@ box_opened2( sync_vars_t *svars, int t )
 				opts[1-t] |= OPEN_OLD;
 			if (chan->ops[t] & OP_NEW)
 				opts[1-t] |= OPEN_NEW;
-			if (chan->ops[t] & OP_EXPUNGE)
+			if (chan->ops[t] & OP_EXPUNGE)  // Don't propagate doomed msgs
 				opts[1-t] |= OPEN_FLAGS;
 			if (chan->stores[t]->max_size != UINT_MAX) {
 				if (chan->ops[t] & OP_RENEW)

src/sync.h

@@ -40,6 +40,7 @@
 #define XOP_PULL           (1<<9)
 #define  XOP_MASK_DIR      (XOP_PUSH|XOP_PULL)
 #define XOP_HAVE_TYPE      (1<<10)
+// The following must all have the same bit shift from the corresponding OP_* flags.
 #define XOP_HAVE_EXPUNGE   (1<<11)
 #define XOP_HAVE_CREATE    (1<<12)
 #define XOP_HAVE_REMOVE    (1<<13)