Add phpdoc explaining the use of transients for awareness

Author: mindctrl

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

@@ -93,6 +93,11 @@ public function add_update( string $room, $update ): bool {
 	/**
 	 * Gets awareness state for a given room.
 	 *
+	 * Awareness data is stored in a transient with a short TTL. Transients may
+	 * be evicted at any time (cache flush, deploy, expiration), in which case
+	 * this method returns an empty array and clients briefly appear offline
+	 * until the next poll repopulates state (typically under one second).
+	 *
 	 * @since 7.0.0
 	 *
 	 * @param string $room Room identifier.
@@ -111,6 +116,11 @@ public function get_awareness_state( string $room ): array {
 	/**
 	 * Sets awareness state for a given room.
 	 *
+	 * Uses a transient rather than post meta to avoid database write churn,
+	 * since awareness data (cursor positions, selections) is ephemeral and
+	 * repopulated on every client poll. A cache eviction only causes a brief
+	 * flicker rather than data loss.
+	 *
 	 * @since 7.0.0
 	 *
 	 * @param string            $room      Room identifier.