docs: vrr clarifications

toml-spec/spec/spec.yaml

@@ -3178,7 +3178,8 @@ Vrr:
       description: |
         The VRR cursor refresh rate.
         
-        Limits the rate at which cursors are updated on screen when VRR is active.
+        Limits the rate at which cursor movement forces a screen update
+        when VRR is active.
 
 
 VrrMode:
@@ -3201,12 +3202,15 @@ VrrMode:
     - value: variant2
       description: VRR is enabled when a single application is displayed fullscreen.
     - value: variant3
-      description: VRR is enabled when a single game or video is displayed fullscreen.
+      description: |
+        VRR is enabled when a single application is displayed fullscreen and
+        describes its content type as video or game through the
+        wp_content_type_v1 protocol.
 
 
 VrrHz:
   description: |
-    A VRR refresh rate limiter.
+    A VRR cursor refresh rate limit.
 
     - Example 1:
     
@@ -3222,10 +3226,31 @@ VrrHz:
   kind: variable
   variants:
     - kind: string
-      description: The string `none` can be used to disable the limiter.
-    - kind: number
-      description: The refresh rate in HZ.
+      description: |
+        The string `none` can be used to disable the limit.
 
+        This means the cursor refresh rate is unbounded, meaning every mouse
+        movement will update the screen.
+
+        If the mouse reporting interval (polling rate) is >= screen refresh
+        rate, this results in the screen spiking to maximum refresh rate on
+        mouse movement.
+    - kind: number
+      description: |
+        The cursor refresh rate limit in Hz.
+
+        This means the cursor is updated whenever the rest of the screen is
+        updated but no later than `1 / cursor-hz` after the last screen update.
+
+        If the application's content refresh rate is higher than `cursor-hz`,
+        the cursor will update with the content.
+
+        Setting `cursor-hz = 1` would force it to always match content refresh
+        rate.
+
+        However, if content refresh rate regularly drops low, cursor movement
+        will feel choppy. Consider setting `cursor-hz` to a reasonable minimum
+        value to keep cursor movement smooth.
 
 Tearing:
   kind: table