wake lock: Update spec references and URLs.

Adjust the comments in source and IDL files to match the latest version of
the spec (5155c2030bf at the time of writing) following the implementation
update commits that landed earlier this week.

Bug: 257511
Change-Id: I5d7b89e7f878a70af08f0dddf399685d496e6fae
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1869215
Commit-Queue: Raphael Kubo da Costa <raphael.kubo.da.costa@intel.com>
Auto-Submit: Raphael Kubo da Costa <raphael.kubo.da.costa@intel.com>
Reviewed-by: Reilly Grant <reillyg@chromium.org>
Cr-Commit-Position: refs/heads/master@{#707756}

third_party/blink/renderer/modules/wake_lock/navigator_wake_lock.idl

@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// https://w3c.github.io/wake-lock/#extensions-to-the-navigator-interface
+
 [
   ImplementedAs=NavigatorWakeLock,
   RuntimeEnabled=WakeLock,

third_party/blink/renderer/modules/wake_lock/wake_lock.cc

@@ -40,7 +40,7 @@ WakeLock::WakeLock(DedicatedWorkerGlobalScope& worker_scope)
                                                       WakeLockType::kSystem)} {}
 
 ScriptPromise WakeLock::request(ScriptState* script_state, const String& type) {
-  // https://w3c.github.io/wake-lock/#request-static-method
+  // https://w3c.github.io/wake-lock/#the-request-method
   auto* context = ExecutionContext::From(script_state);
   DCHECK(context->IsDocument() || context->IsDedicatedWorkerGlobalScope());
 
@@ -110,6 +110,7 @@ ScriptPromise WakeLock::request(ScriptState* script_state, const String& type) {
     }
   }
 
+  // 1. Let promise be a new promise.
   auto* resolver = MakeGarbageCollected<ScriptPromiseResolver>(script_state);
   ScriptPromise promise = resolver->Promise();
 
@@ -127,10 +128,8 @@ ScriptPromise WakeLock::request(ScriptState* script_state, const String& type) {
       break;
   }
 
-  // 6. Run the following steps in parallel, but abort when options' signal
-  // member is present and its aborted flag is set:
-  // 6.1. Let state be the result of awaiting obtain permission steps with
-  //      type:
+  // 5. Run the following steps in parallel, but abort when type is "screen" and
+  // document is hidden:
   DoRequest(wake_lock_type, resolver);
 
   // 7. Return promise.
@@ -138,6 +137,8 @@ ScriptPromise WakeLock::request(ScriptState* script_state, const String& type) {
 }
 
 void WakeLock::DoRequest(WakeLockType type, ScriptPromiseResolver* resolver) {
+  // https://w3c.github.io/wake-lock/#the-request-method
+  // 5.1. Let state be the result of awaiting obtain permission steps with type:
   ObtainPermission(
       type, WTF::Bind(&WakeLock::DidReceivePermissionResponse,
                       WrapPersistent(this), type, WrapPersistent(resolver)));
@@ -146,11 +147,11 @@ void WakeLock::DoRequest(WakeLockType type, ScriptPromiseResolver* resolver) {
 void WakeLock::DidReceivePermissionResponse(WakeLockType type,
                                             ScriptPromiseResolver* resolver,
                                             PermissionStatus status) {
-  // https://w3c.github.io/wake-lock/#request-static-method
+  // https://w3c.github.io/wake-lock/#the-request-method
   DCHECK(status == PermissionStatus::GRANTED ||
          status == PermissionStatus::DENIED);
   DCHECK(resolver);
-  // 6.1.1. If state is "denied", then reject promise with a "NotAllowedError"
+  // 5.1.1. If state is "denied", then reject promise with a "NotAllowedError"
   //        DOMException, and abort these steps.
   if (status != PermissionStatus::GRANTED) {
     resolver->Reject(MakeGarbageCollected<DOMException>(
@@ -158,9 +159,8 @@ void WakeLock::DidReceivePermissionResponse(WakeLockType type,
         "Wake Lock permission request denied"));
     return;
   }
-  // https://github.com/w3c/wake-lock/issues/222: the page can become hidden
-  // between request() and WakeLockManager::AcquireWakeLock(), in which case
-  // we need to abort early.
+  // 6. If aborted, run these steps:
+  // 6.1. Reject promise with a "NotAllowedError" DOMException.
   if (type == WakeLockType::kScreen &&
       !(GetPage() && GetPage()->IsPageVisible())) {
     resolver->Reject(MakeGarbageCollected<DOMException>(
@@ -168,9 +168,9 @@ void WakeLock::DidReceivePermissionResponse(WakeLockType type,
         "The requesting page is not visible"));
     return;
   }
-  // 6.2. Let success be the result of awaiting acquire a wake lock with promise
+  // 5.3. Let success be the result of awaiting acquire a wake lock with lock
   // and type:
-  // 6.2.1. If success is false then reject promise with a "NotAllowedError"
+  // 5.3.1. If success is false then reject promise with a "NotAllowedError"
   //        DOMException, and abort these steps.
   WakeLockManager* manager = managers_[static_cast<size_t>(type)];
   DCHECK(manager);
@@ -182,12 +182,12 @@ void WakeLock::ContextDestroyed(ExecutionContext*) {
   // 1. Let document be the responsible document of the current settings object.
   // 2. Let screenRecord be the platform wake lock's state record associated
   // with document and wake lock type "screen".
-  // 3. For each lockPromise in screenRecord.[[ActiveLocks]]:
-  // 3.1. Run release a wake lock with lockPromise and "screen".
+  // 3. For each lock in screenRecord.[[ActiveLocks]]:
+  // 3.1. Run release a wake lock with lock and "screen".
   // 4. Let systemRecord be the platform wake lock's state record associated
   // with document and wake lock type "system".
-  // 5. For each lockPromise in systemRecord.[[ActiveLocks]]:
-  // 5.1. Run release a wake lock with lockPromise and "system".
+  // 5. For each lock in systemRecord.[[ActiveLocks]]:
+  // 5.1. Run release a wake lock with lock and "system".
   for (WakeLockManager* manager : managers_) {
     if (manager)
       manager->ClearWakeLocks();
@@ -202,8 +202,8 @@ void WakeLock::PageVisibilityChanged() {
     return;
   // 3. Let screenRecord be the platform wake lock's state record associated
   // with wake lock type "screen".
-  // 4. For each lockPromise in screenRecord.[[ActiveLocks]]:
-  // 4.1. Run release a wake lock with lockPromise and "screen".
+  // 4. For each lock in screenRecord.[[ActiveLocks]]:
+  // 4.1. Run release a wake lock with lock and "screen".
   WakeLockManager* manager =
       managers_[static_cast<size_t>(WakeLockType::kScreen)];
   if (manager)

third_party/blink/renderer/modules/wake_lock/wake_lock_manager.cc

@@ -34,7 +34,7 @@ void WakeLockManager::AcquireWakeLock(ScriptPromiseResolver* resolver) {
   //      object.
   // 4.2. Let record be the platform wake lock's state record associated with
   //      document and type.
-  // 4.3. Add lockPromise to record.[[ActiveLocks]].
+  // 4.3. Add lock to record.[[ActiveLocks]].
   // 5. Return active.
   if (!wake_lock_) {
     mojo::Remote<mojom::blink::WakeLockService> wake_lock_service;
@@ -49,6 +49,10 @@ void WakeLockManager::AcquireWakeLock(ScriptPromiseResolver* resolver) {
         &WakeLockManager::OnWakeLockConnectionError, WrapWeakPersistent(this)));
     wake_lock_->RequestWakeLock();
   }
+  // https://w3c.github.io/wake-lock/#the-request-method
+  // 5.2. Let lock be a new WakeLockSentinel object with its type attribute set
+  // to type.
+  // 5.4. Resolve promise with lock.
   auto* sentinel = MakeGarbageCollected<WakeLockSentinel>(
       resolver->GetScriptState(), wake_lock_type_, this);
   wake_lock_sentinels_.insert(sentinel);
@@ -56,13 +60,29 @@ void WakeLockManager::AcquireWakeLock(ScriptPromiseResolver* resolver) {
 }
 
 void WakeLockManager::UnregisterSentinel(WakeLockSentinel* sentinel) {
+  // https://w3c.github.io/wake-lock/#release-wake-lock-algorithm
+  // 1. Let document be the responsible document of the current settings object.
+  // 2. Let record be the platform wake lock's state record associated with
+  // document and type.
+  // 3. If record.[[ActiveLocks]] does not contain lock, abort these steps.
   auto iterator = wake_lock_sentinels_.find(sentinel);
   DCHECK(iterator != wake_lock_sentinels_.end());
+
+  // 4. Remove lock from record.[[ActiveLocks]].
   wake_lock_sentinels_.erase(iterator);
 
+  // 5. If the internal slot [[ActiveLocks]] of all the platform wake lock's
+  // state records are all empty, then run the following steps in parallel:
+  // 5.1. Ask the underlying operation system to release the wake lock of type
+  //      type and let success be true if the operation succeeded, or else
+  //      false.
   if (wake_lock_sentinels_.IsEmpty() && wake_lock_.is_bound()) {
     wake_lock_->CancelWakeLock();
     wake_lock_.reset();
+
+    // 5.2. If success is true and type is "screen" run the following:
+    // 5.2.1. Reset the platform-specific inactivity timer after which the
+    //        screen is actually turned off.
   }
 }
 

third_party/blink/renderer/modules/wake_lock/wake_lock_sentinel.cc

@@ -23,11 +23,20 @@ WakeLockSentinel::WakeLockSentinel(ScriptState* script_state,
 WakeLockSentinel::~WakeLockSentinel() = default;
 
 ScriptPromise WakeLockSentinel::release(ScriptState* script_state) {
+  // https://w3c.github.io/wake-lock/#the-release-method
+  // 1. Let promise be a new promise.
+  // 2. Run the following steps in parallel:
+  // 2.1. Run release wake lock with lock set to this object and type set to the
+  //      value of this object's type attribute.
+  // 2.2. Resolve promise.
+  // 3. Return promise.
   DoRelease();
   return ScriptPromise::CastUndefined(script_state);
 }
 
 String WakeLockSentinel::type() const {
+  // https://w3c.github.io/wake-lock/#dom-wakelocksentinel-type
+  // The type attribute corresponds to the WakeLockSentinel's wake lock type.
   switch (type_) {
     case WakeLockType::kScreen:
       return "screen";
@@ -65,12 +74,18 @@ void WakeLockSentinel::ContextDestroyed(ExecutionContext*) {
 }
 
 void WakeLockSentinel::DoRelease() {
+  // https://w3c.github.io/wake-lock/#release-wake-lock-algorithm
+  // 1. Let document be the responsible document of the current settings object.
+  // 2. Let record be the platform wake lock's state record associated with
+  // document and type.
+  // 3. If record.[[ActiveLocks]] does not contain lock, abort these steps.
   if (!manager_)
     return;
 
   manager_->UnregisterSentinel(this);
   manager_.Clear();
 
+  // 6. Queue a task to fire an event named "release" at lock.
   DispatchEvent(*Event::Create(event_type_names::kRelease));
 }
 

third_party/blink/renderer/modules/wake_lock/wake_lock_sentinel.idl

@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// https://w3c.github.io/wake-lock/#the-wakelocksentinel-interface
+
 [
   ActiveScriptWrappable,
   Exposed=(DedicatedWorker,Window),

third_party/blink/renderer/modules/wake_lock/worker_navigator_wake_lock.idl

@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// https://w3c.github.io/wake-lock/#extensions-to-the-workernavigator-interface
+
 [
   ImplementedAs=WorkerNavigatorWakeLock,
   RuntimeEnabled=WakeLock,