5 files changed, 24 insertions, 10 deletions
diff --git a/src/compiler/optimize/doctype.ts b/src/compiler/optimize/doctype.ts
index fdf6c4078..176880c08 100644
--- a/src/compiler/optimize/doctype.ts
+++ b/src/compiler/optimize/doctype.ts
@@ -1,5 +1,6 @@
 import { Optimizer } from '../../@types/optimizer';
 
+/** Optimize <!doctype> tg */
 export default function (_opts: { filename: string; fileID: string }): Optimizer {
   let hasDoctype = false;
 
diff --git a/src/compiler/optimize/index.ts b/src/compiler/optimize/index.ts
index 53dd3f2d6..a7bf828e0 100644
--- a/src/compiler/optimize/index.ts
+++ b/src/compiler/optimize/index.ts
@@ -13,6 +13,7 @@ interface VisitorCollection {
   leave: Map<string, VisitorFn[]>;
 }
 
+/** Add visitors to given collection */
 function addVisitor(visitor: NodeVisitor, collection: VisitorCollection, nodeName: string, event: 'enter' | 'leave') {
   if (typeof visitor[event] !== 'function') return;
   if (!collection[event]) collection[event] = new Map<string, VisitorFn[]>();
@@ -22,6 +23,7 @@ function addVisitor(visitor: NodeVisitor, collection: VisitorCollection, nodeNam
   collection[event].set(nodeName, visitors);
 }
 
+/** Compile visitor actions from optimizer */
 function collectVisitors(optimizer: Optimizer, htmlVisitors: VisitorCollection, cssVisitors: VisitorCollection, finalizers: Array<() => Promise<void>>) {
   if (optimizer.visitors) {
     if (optimizer.visitors.html) {
@@ -40,6 +42,7 @@ function collectVisitors(optimizer: Optimizer, htmlVisitors: VisitorCollection,
   finalizers.push(optimizer.finalize);
 }
 
+/** Utility for formatting visitors */
 function createVisitorCollection() {
   return {
     enter: new Map<string, VisitorFn[]>(),
@@ -47,6 +50,7 @@ function createVisitorCollection() {
   };
 }
 
+/** Walk AST with collected visitors */
 function walkAstWithVisitors(tmpl: TemplateNode, collection: VisitorCollection) {
   walk(tmpl, {
     enter(node, parent, key, index) {
@@ -68,6 +72,12 @@ function walkAstWithVisitors(tmpl: TemplateNode, collection: VisitorCollection)
   });
 }
 
+/**
+ * Optimize
+ * Step 2/3 in Astro SSR.
+ * Optimize is the point at which we mutate the AST before sending off to
+ * Codegen, and then to Snowpack. In some ways, it‘s a preprocessor.
+ */
 export async function optimize(ast: Ast, opts: OptimizeOptions) {
   const htmlVisitors = createVisitorCollection();
   const cssVisitors = createVisitorCollection();
diff --git a/src/compiler/optimize/module-scripts.ts b/src/compiler/optimize/module-scripts.ts
index 713747fcb..9d4949215 100644
--- a/src/compiler/optimize/module-scripts.ts
+++ b/src/compiler/optimize/module-scripts.ts
@@ -4,6 +4,7 @@ import type { CompileOptions } from '../../@types/compiler';
 import path from 'path';
 import { getAttrValue, setAttrValue } from '../../ast.js';
 
+/** Optimize <script type="module"> */
 export default function ({ compileOptions, filename }: { compileOptions: CompileOptions; filename: string; fileID: string }): Optimizer {
   const { astroConfig } = compileOptions;
   const { astroRoot } = astroConfig;
diff --git a/src/compiler/optimize/postcss-scoped-styles/index.ts b/src/compiler/optimize/postcss-scoped-styles/index.ts
index a4afd99aa..0d1253350 100644
--- a/src/compiler/optimize/postcss-scoped-styles/index.ts
+++ b/src/compiler/optimize/postcss-scoped-styles/index.ts
@@ -24,15 +24,17 @@ export function scopeSelectors(selector: string, className: string) {
   let ss = selector; // final output
 
   // Pass 1: parse selector string; extract top-level selectors
-  let start = 0;
-  let lastValue = '';
-  for (let n = 0; n < ss.length; n++) {
-    const isEnd = n === selector.length - 1;
-    if (isEnd || CSS_SEPARATORS.has(selector[n])) {
-      lastValue = selector.substring(start, isEnd ? undefined : n);
-      if (!lastValue) continue;
-      selectors.push({ start, end: isEnd ? n + 1 : n, value: lastValue });
-      start = n + 1;
+  {
+    let start = 0;
+    let lastValue = '';
+    for (let n = 0; n < ss.length; n++) {
+      const isEnd = n === selector.length - 1;
+      if (isEnd || CSS_SEPARATORS.has(selector[n])) {
+        lastValue = selector.substring(start, isEnd ? undefined : n);
+        if (!lastValue) continue;
+        selectors.push({ start, end: isEnd ? n + 1 : n, value: lastValue });
+        start = n + 1;
+      }
     }
   }
 
diff --git a/src/compiler/optimize/styles.ts b/src/compiler/optimize/styles.ts
index b613e4845..36e6f1d7d 100644
--- a/src/compiler/optimize/styles.ts
+++ b/src/compiler/optimize/styles.ts
@@ -106,7 +106,7 @@ async function transformStyle(code: string, { type, filename, scopedClass, mode
   return { css, type: styleType };
 }
 
-/** Style optimizer */
+/** Optimize <style> tags */
 export default function optimizeStyles({ compileOptions, filename, fileID }: OptimizeOptions): Optimizer {
   const styleNodes: TemplateNode[] = []; // <style> tags to be updated
   const styleTransformPromises: Promise<StyleTransformResult>[] = []; // async style transform results to be finished in finalize();