stores: add comments

stores/sql/main.go

@@ -1877,10 +1877,19 @@ func RenameDirectories(ctx context.Context, tx Tx, bucket, prefixOld, prefixNew
 		if err := queryDirStmt.QueryRow(ctx, d.name, bucketID).Scan(&existingID); err != nil && !errors.Is(err, dsql.ErrNoRows) {
 			return 0, err
 		} else if existingID > 0 {
+			// case 1: the target directory already exists, in this case we want
+			// to update all of the directories that were pointing to the
+			// directory we're renaming, to point to the existing target
+			// directory
 			if _, err := updateChildrenStmt.Exec(ctx, existingID, d.id); err != nil {
 				return 0, err
 			}
 		} else {
+			// case 2: the target directory does not exist, but we do have a
+			// directory we want to rename, in this case we want to update the
+			// name of the directory but also ensure its pointing to the correct
+			// parent, e.g. we might be moving a folder up or downwards in the
+			// directory tree structure
 			parentID, err := tx.InsertDirectories(ctx, bucket, d.name)
 			if err != nil {
 				return 0, err