Re: [w3c/gamepad] Move vibrationActuator to the main spec (PR #190)

@toji commented on this pull request.



> +          Promise<boolean> pulse(double value, double duration);
+        };
+      </pre>
+      <dt>
+        <dfn>pulse()</dfn> method
+      </dt>
+      <dd>
+        <p>
+          <code>pulse()</code> applies a <var>value</var> to the actuator for
+          <var>duration</var> milliseconds. The <var>value</var> passed to
+          <code>pulse()</code> is clamped to limits defined by the actuator
+          type. The returned Promise will resolve <code>true</code> once the
+          pulse has completed.
+        </p>
+        <p>
+          Repeated calls to <code>pulse()</code> override the previous

Broadly agree with @marcoscaceres that we should evaluate whether or not `pulse()` is actually desired going forward. I'll also throw up the @cabanier bat signal here to get Meta's take on it.

Re: the intent behind the `pulse()` promise resolution...
![84_Years](https://github.com/w3c/gamepad/assets/805273/b349d91c-52f3-44a1-b065-e3f193857784)

It _has_ been a while, so I don't recall the details of the conversation around this API. But I do recall having conversations with the TAG in regards to similarly shaped APIs at around the same time. Specifically the [WebXR `isSessionSupported()` API](https://immersive-web.github.io/webxr/#xrsystem-interface), which also resolves to a boolean value. 

Originally we were going to have the promise resolve with void if the session type was supported and reject otherwise but the guidance we received was that rejection should only happen in the case of something truly exceptional, where the intent of the method called could not be fulfilled. This is especially true when you consider that many promises are used with async/await patterns, and the only way to observe the rejection is a try/catch. That's fairly disruptive. In the case of `isSessionSupported()` the question being asked (can I start this kind of session) could always be answered yes or no, so resolving with a boolean made sense and the method never rejects.

With that framing in mind, the fact that this resolves to a boolean rather than void tells me that the boolean was intended to communicate information. It feels to my like the intent was "resolve when the requested pulse is finished, with true if it was allowed to complete and false if it was pre-empted." I wouldn't expect it to reject unless perhaps the pulse simply couldn't be rendered by the device haptics at all? Even then it seems possibly more ergonomic to never reject.

Whether or not that's what the Meta implementation does is an entirely different story.

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

Message ID: <w3c/gamepad/pull/190/review/1754009583@github.com>