[Script Spec Annotation] Annotate "prepare a script"

third_party/WebKit/Source/core/html/parser/HTMLParserScriptRunner.cpp

 /*
  * Copyright (C) 2010 Google, Inc. All Rights Reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
@@ skipping 420 matching lines @@
     }
     PendingScript* first = m_scriptsToExecuteAfterParsing.takeFirst();
     executePendingScriptAndDispatchEvent(first, ScriptStreamer::Deferred);
     // FIXME: What is this m_document check for?
     if (!m_document)
       return false;
   }
   return true;
 }
 
+// 2nd Clause, Step 23 of https://html.spec.whatwg.org/#prepare-a-script
 void HTMLParserScriptRunner::requestParsingBlockingScript(Element* element) {
+  // "The element is the pending parsing-blocking script of the Document of
+  //  the parser that created the element.
+  //  (There can only be one such script per Document at a time.)"
   if (!requestPendingScript(m_parserBlockingScript.get(), element))
     return;
 
   DCHECK(m_parserBlockingScript->resource());
 
   // We only care about a load callback if resource is not already in the cache.
   // Callers will attempt to run the m_parserBlockingScript if possible before
   // returning control to the parser.
   if (!m_parserBlockingScript->isReady()) {
     if (m_document->frame()) {
       ScriptState* scriptState = ScriptState::forMainWorld(m_document->frame());
       if (scriptState) {
         ScriptStreamer::startStreaming(
             m_parserBlockingScript.get(), ScriptStreamer::ParsingBlocking,
             m_document->frame()->settings(), scriptState,
             TaskRunnerHelper::get(TaskType::Networking, m_document));
       }
     }
 
     m_parserBlockingScript->watchForLoad(this);
   }
 }
 
+// 1st Clause, Step 23 of https://html.spec.whatwg.org/#prepare-a-script
 void HTMLParserScriptRunner::requestDeferredScript(Element* element) {
   PendingScript* pendingScript = PendingScript::create(nullptr, nullptr);
   if (!requestPendingScript(pendingScript, element))
     return;
 
   if (m_document->frame() && !pendingScript->isReady()) {
     ScriptState* scriptState = ScriptState::forMainWorld(m_document->frame());
     if (scriptState) {
       ScriptStreamer::startStreaming(
           pendingScript, ScriptStreamer::Deferred,
           m_document->frame()->settings(), scriptState,
           TaskRunnerHelper::get(TaskType::Networking, m_document));
     }
   }
 
   DCHECK(pendingScript->resource());
+
+  // "Add the element to the end of the list of scripts that will execute
+  //  when the document has finished parsing associated with the Document
+  //  of the parser that created the element."
   m_scriptsToExecuteAfterParsing.append(pendingScript);
 }
 
 bool HTMLParserScriptRunner::requestPendingScript(PendingScript* pendingScript,
                                                   Element* script) const {
   DCHECK(!pendingScript->element());
   pendingScript->setElement(script);
   // This should correctly return 0 for empty or invalid srcValues.
   ScriptResource* resource = toScriptLoaderIfPossible(script)->resource();
   if (!resource) {
@@ skipping 27 matching lines @@
     if (!isExecutingScript())
       Microtask::performCheckpoint(V8PerIsolateData::mainThreadIsolate());
 
     InsertionPointRecord insertionPointRecord(m_host->inputStream());
     HTMLParserReentryPermit::ScriptNestingLevelIncrementer
         nestingLevelIncrementer =
             m_reentryPermit->incrementScriptNestingLevel();
 
     scriptLoader->prepareScript(scriptStartPosition);
 
+    // A part of Step 23 of https://html.spec.whatwg.org/#prepare-a-script:
     if (!scriptLoader->willBeParserExecuted())
       return;
 
     if (scriptLoader->willExecuteWhenDocumentFinishedParsing()) {
+      // 1st Clause of Step 23.
       requestDeferredScript(script);
     } else if (scriptLoader->readyToBeParserExecuted()) {
+      // 5th Clause of Step 23.
+      // "If ... it's an HTML parser
+      //  whose script nesting level is not greater than one"
       if (m_reentryPermit->scriptNestingLevel() == 1u) {
+        // "The element is the pending parsing-blocking script of the
+        //  Document of the parser that created the element.
+        //  (There can only be one such script per Document at a time.)"
         m_parserBlockingScript->setElement(script);
         m_parserBlockingScript->setStartingPosition(scriptStartPosition);
       } else {
+        // 6th Clause of Step 23.
+        // "Immediately execute the script block,
+        //  even if other scripts are already executing."
+        // TODO(hiroshige): Merge the block into ScriptLoader::prepareScript().
         DCHECK_GT(m_reentryPermit->scriptNestingLevel(), 1u);
         m_parserBlockingScript->dispose();
         ScriptSourceCode sourceCode(script->textContent(),
                                     documentURLForScriptExecution(m_document),
                                     scriptStartPosition);
         doExecuteScript(script, sourceCode, scriptStartPosition);
       }
     } else {
+      // 2nd Clause of Step 23.
       requestParsingBlockingScript(script);
     }
   }
 }
 
 DEFINE_TRACE(HTMLParserScriptRunner) {
   visitor->trace(m_document);
   visitor->trace(m_host);
   visitor->trace(m_parserBlockingScript);
   visitor->trace(m_scriptsToExecuteAfterParsing);
   PendingScriptClient::trace(visitor);
 }
 
 }  // namespace blink