diff --git a/cmdline/elem.h b/cmdline/elem.h
index ef9aa6c5..3dd00999 100644
--- a/cmdline/elem.h
+++ b/cmdline/elem.h
@@ -80,11 +80,11 @@ struct snapraid_filter {
  * The block is new and not yet hashed.
  * This happens when a new block overwrite a just removed block, or an empty space.
  *
- * The block hash field IS set but it may be also INVALID or ZERO,
- * and it represents the hash of the OLD data.
+ * The block hash field MAY be set and it represents the hash of the OLD data.
+ * The hash may be also INVALID or ZERO.
  *
- * If the block was empty, the hash is set to the special ZERO value.
- * If the block was lost, the hash is set to the special INVALID value.
+ * If the OLD block was empty, the hash is set to the special ZERO value.
+ * If the OLD block was lost, the hash is set to the special INVALID value.
  *
  * The parity for this disk is not updated, but it contains the old data referenced by the hash.
  *
diff --git a/cmdline/sync.c b/cmdline/sync.c
index 2c87e25f..1318a0e1 100644
--- a/cmdline/sync.c
+++ b/cmdline/sync.c
@@ -739,6 +739,8 @@ static int state_sync_process(struct snapraid_state* state, struct snapraid_pari
 		}
 
 		/* if we have only silent errors we can try to fix them on-the-fly */
+		/* note the the fix is not written to disk, but used only to */
+		/* compute the new parity */
 		if (!error_on_this_block && silent_error_on_this_block) {
 			unsigned failed_mac;
 			int something_to_recover = 0;