Re: [w3c/gamepad] Spec liveness of Gamepad and GamepadButton objects (#8) (#123)

marcoscaceres requested changes on this pull request.



> @@ -209,7 +209,11 @@ <h2>
         <dfn>Gamepad</dfn> interface
       </h2>
       <p>
-        This interface defines an individual gamepad device.
+        This interface represents an individual gamepad device. A Gamepad is a
+        live object; that is, user interaction with the device will be reflected
+        in the state of the object's properties. When the system receives new
+        data from a connected gamepad, a microtask is queued in the current

Can probably drop "in the current event loop" as that's a bit ambiguous. 

I wonder if we should use the "user interaction task source"? 

> @@ -209,7 +209,11 @@ <h2>
         <dfn>Gamepad</dfn> interface
       </h2>
       <p>
-        This interface defines an individual gamepad device.
+        This interface represents an individual gamepad device. A Gamepad is a
+        live object; that is, user interaction with the device will be reflected
+        in the state of the object's properties. When the system receives new
+        data from a connected gamepad, a microtask is queued in the current
+        event loop to update the state of the Gamepad object.

```suggestion
        event loop to update the state of the {{Gamepad}} object.
```

>          </dd>
         <dt>
           <dfn>buttons</dfn> attribute
         </dt>
         <dd>
-          Array of button states for all buttons of the gamepad. It is
+          Array of GamepadButton objects representing all buttons of the gamepad. It is

```suggestion
          Array of {{GamepadButton}} objects representing all buttons of the gamepad. It is
```

>            RECOMMENDED that buttons appear in decreasing importance such that
           the primary button, secondary button, tertiary button, and so on
           appear as elements 0, 1, 2, ... in the buttons array. The same object
-          MUST be returned until the <a>user agent</a> needs to return
-          different values (or values in a different order).
+          MUST be returned until the <a>user agent</a> needs to modify the
+          length of the array or the button ordering.

This is somewhat ambiguous... it could be read like, if an axis changes, then replace all every `GamepadButton`.  

> @@ -318,7 +323,13 @@ <h2>
       </h2>
       <p>
         This interface defines the state of an individual button on a gamepad
-        device.
+        device. A GamepadButton is a live object; that is, user interaction with

```suggestion
        device. A {{GamepadButton}} is a live object; that is, user interaction with
```

> @@ -318,7 +323,13 @@ <h2>
       </h2>
       <p>
         This interface defines the state of an individual button on a gamepad
-        device.
+        device. A GamepadButton is a live object; that is, user interaction with

I think this should just read:
"A {{GamepadButton}} is a live object: When the system receives new data from a connected gamepad..." 

And drop the "that is, user interaction with....". That makes it more clear that updates to the various properties are dependent on the queued microtasks. 

> @@ -318,7 +323,13 @@ <h2>
       </h2>
       <p>
         This interface defines the state of an individual button on a gamepad
-        device.
+        device. A GamepadButton is a live object; that is, user interaction with
+        the button represented by the object will be reflected in the object's
+        properties. When the system receives new data from a connected gamepad,
+        a microtask is queued in the current event loop to update the state of
+        the GamepadButton object. If a gamepad device is disconnected, the

The "If a gamepad device is disconnected..." should probably be it's own paragraph. Eventually, we need to turn that also into a queued task... "Upon disconnection of a gamepad, queue a task to... "    

> @@ -416,7 +427,7 @@ <h2>
           <dfn>getGamepads</dfn>
         </dt>
         <dd>
-          Retrieve a snapshot of the data for the the currently connected and
+          Retrieve an array of Gamepad objects representing currently connected and

```suggestion
          Retrieve a sequence of {{Gamepad}} objects representing currently connected and
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/gamepad/pull/123#pullrequestreview-306998388