From da1056fc7b21b42504c7139e12fd042eb3344efc Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:16:21 +0000
Subject: [PATCH 01/16] Trim excessive comments in src/article-api lib,
 middleware, and scripts (#63279)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/article-api/lib/get-all-toc-items.ts      | 11 --------
 src/article-api/lib/get-link-data.ts          | 10 ++-----
 src/article-api/lib/graphql-helpers.ts        |  5 +---
 src/article-api/lib/load-template.ts          | 22 ++--------------
 src/article-api/lib/strip-html-comments.ts    | 21 ++-------------
 src/article-api/lib/summarize-schema.ts       |  4 ---
 src/article-api/liquid-renderers/index.ts     |  9 +------
 src/article-api/liquid-renderers/rest-tags.ts | 26 +++----------------
 src/article-api/middleware/article-body.ts    |  8 +-----
 src/article-api/middleware/pagelist.ts        |  7 -----
 src/article-api/middleware/validation.ts      | 13 ++--------
 src/article-api/scripts/generate-api-docs.ts  | 15 +----------
 12 files changed, 15 insertions(+), 136 deletions(-)

diff --git a/src/article-api/lib/get-all-toc-items.ts b/src/article-api/lib/get-all-toc-items.ts
index bf3e94824931..985bb2667c1c 100644
--- a/src/article-api/lib/get-all-toc-items.ts
+++ b/src/article-api/lib/get-all-toc-items.ts
@@ -19,11 +19,6 @@ interface TocItem extends LinkData {
  * Recursively gathers all TOC items from a page and its descendants.
  * This mirrors the behavior of getTocItems() in the generic-toc middleware
  * but works with the page.children frontmatter property.
- *
- * @param page - The page to gather TOC items from
- * @param context - The rendering context
- * @param options - Configuration options
- * @returns Array of TocItems with nested childTocItems
  */
 export async function getAllTocItems(
   page: Page,
@@ -41,7 +36,6 @@ export async function getAllTocItems(
     return []
   }
 
-  // Get the page's pathname for resolving children
   const pagePermalink = page.permalinks.find(
     (p) => p.languageCode === languageCode && p.pageVersion === context.currentVersion,
   )
@@ -92,10 +86,6 @@ export async function getAllTocItems(
 /**
  * Flattens nested TOC items into a single array.
  * Only includes leaf nodes (items without children) or all items based on options.
- *
- * @param tocItems - The nested TOC items to flatten
- * @param options - Configuration options
- * @returns Flat array of LinkData items
  */
 export function flattenTocItems(
   tocItems: TocItem[],
@@ -125,7 +115,6 @@ export function flattenTocItems(
         }
       }
 
-      // Recurse into children
       if (hasChildren) {
         recurse(item.childTocItems!)
       }
diff --git a/src/article-api/lib/get-link-data.ts b/src/article-api/lib/get-link-data.ts
index f9c33c74608e..45749ec06a0e 100644
--- a/src/article-api/lib/get-link-data.ts
+++ b/src/article-api/lib/get-link-data.ts
@@ -5,15 +5,9 @@ import type { LinkData } from '@/article-api/transformers/types'
  * Resolves link data (title, href, intro) for a given href and page
  *
  * This helper is used by landing page transformers to build link lists.
- * It resolves the page from an href, renders its title and intro, and
+ * It resolves the page from an href (relative or absolute), renders its title
+ * and intro, and
  * returns the canonical permalink.
- *
- * @param href - The href to resolve (can be relative or absolute)
- * @param languageCode - The language code for the current page
- * @param pathname - The current page's pathname (for relative resolution)
- * @param context - The rendering context
- * @param resolvePath - Function to resolve an href to a Page object
- * @returns LinkData with resolved title, href, and optional intro
  */
 export async function getLinkData(
   href: string,
diff --git a/src/article-api/lib/graphql-helpers.ts b/src/article-api/lib/graphql-helpers.ts
index 6db482d7ff06..dc07ef55ca18 100644
--- a/src/article-api/lib/graphql-helpers.ts
+++ b/src/article-api/lib/graphql-helpers.ts
@@ -2,10 +2,7 @@ import type { Context, Page } from '@/types'
 import { renderContent } from '@/content-render/index'
 import matter from '@gr2m/gray-matter'
 
-/**
- * Extract manual content from page markdown
- * Used by GraphQL transformers to get content before the auto-generated marker
- */
+// Returns the part of the page markdown before the auto-generated marker.
 export async function extractManualContent(page: Page, context: Context): Promise<string> {
   if (!page.markdown) return ''
 
diff --git a/src/article-api/lib/load-template.ts b/src/article-api/lib/load-template.ts
index 2cf169ba791b..3e17398756ed 100644
--- a/src/article-api/lib/load-template.ts
+++ b/src/article-api/lib/load-template.ts
@@ -2,30 +2,12 @@ import { readFileSync } from 'fs'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
-// Get the directory path for the transformers directory
-// This will be used to resolve template paths relative to transformers
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
-/**
- * Load a template file from the templates directory
- *
- * This helper loads Liquid template files used by transformers.
- * Templates are located in src/article-api/templates/
- *
- * @param templateName - The name of the template file (e.g., 'landing-page.template.md')
- * @returns The template content as a string
- *
- * @example
- * ```typescript
- * const template = loadTemplate('landing-page.template.md')
- * const rendered = await renderContent(template, context)
- * ```
- */
+// Loads a Liquid template file from src/article-api/templates, for use by
+// transformers.
 export function loadTemplate(templateName: string): string {
-  // Templates are in ../templates relative to the lib directory
-  // lib is at src/article-api/lib
-  // templates is at src/article-api/templates
   const templatePath = join(__dirname, '../templates', templateName)
   return readFileSync(templatePath, 'utf8')
 }
diff --git a/src/article-api/lib/strip-html-comments.ts b/src/article-api/lib/strip-html-comments.ts
index 354bef9b0b63..1f15e67fc084 100644
--- a/src/article-api/lib/strip-html-comments.ts
+++ b/src/article-api/lib/strip-html-comments.ts
@@ -1,27 +1,10 @@
-/**
- * Strips HTML comments from markdown content.
- * Removes single-line HTML comments like <!-- markdownlint-disable GHD053 -->
- * while preserving other content.
- *
- * @param content - The markdown content to process
- * @returns The content with HTML comments removed
- */
+// Removes single-line HTML comments such as <!-- markdownlint-disable GHD053 -->.
 export function stripHtmlComments(content: string): string {
-  // Remove single-line HTML comments (<!-- ... -->)
-  // This matches comments that are on their own line or inline
   return content.replace(/<!--.*?-->/g, '').trim()
 }
 
-/**
- * Strips HTML comments and cleans up extra blank lines.
- * Useful for cleaning up rendered markdown content where HTML comments
- * were on separate lines and their removal creates gaps.
- *
- * @param content - The markdown content to process
- * @returns The content with HTML comments removed and blank lines normalized
- */
+// Strips HTML comments, then collapses the blank lines their removal leaves behind.
 export function stripHtmlCommentsAndNormalizeWhitespace(content: string): string {
-  // Remove HTML comments
   let cleaned = stripHtmlComments(content)
 
   // Normalize multiple consecutive blank lines to at most 2 blank lines
diff --git a/src/article-api/lib/summarize-schema.ts b/src/article-api/lib/summarize-schema.ts
index 8ae39784399b..57f0276d6bd2 100644
--- a/src/article-api/lib/summarize-schema.ts
+++ b/src/article-api/lib/summarize-schema.ts
@@ -194,14 +194,12 @@ export function summarizeSchema(schema: JsonSchema): string {
   // compact and fast to render (shared types can recur dozens of times).
   const seen = new Set<string>()
 
-  // Handle top-level composition
   for (const keyword of ['oneOf', 'anyOf', 'allOf'] as const) {
     if (schema[keyword]) {
       return renderCompositionVariants(keyword, schema[keyword]!, 0, 0, seen)
     }
   }
 
-  // Handle top-level array
   const schemaTypes = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : []
   const isNullable = schemaTypes.includes('null')
   const primaryType = schemaTypes.find((t) => t !== 'null')
@@ -215,7 +213,6 @@ export function summarizeSchema(schema: JsonSchema): string {
     const constraintStr = constraints.length ? ` (${constraints.join(', ')})` : ''
     const itemTitle = items.title
 
-    // Composition inside items
     const compositionKey = (['oneOf', 'anyOf', 'allOf'] as const).find((k) => items[k])
     if (compositionKey) {
       const label = compositionKey.replace('Of', ' of')
@@ -248,7 +245,6 @@ export function summarizeSchema(schema: JsonSchema): string {
     return `Array${constraintStr} of ${renderTypeConstraints(items)}${isNullable ? ' or null' : ''}`
   }
 
-  // Handle top-level object
   if (schema.properties) {
     // Note: we deliberately do NOT pre-mark schema.title here. Unlike the
     // array-items case above, a top-level object emits no visible titled
diff --git a/src/article-api/liquid-renderers/index.ts b/src/article-api/liquid-renderers/index.ts
index b25734dbad69..7b2739dec3ea 100644
--- a/src/article-api/liquid-renderers/index.ts
+++ b/src/article-api/liquid-renderers/index.ts
@@ -1,16 +1,9 @@
-/**
- * API Transformer Liquid Tags
- *
- * This module contains custom Liquid tags used by article-api transformers
- * to render API documentation in a consistent format.
- */
+// Custom Liquid tags used by article-api transformers.
 
 import { restTags } from './rest-tags'
 
-// Export all API transformer tags for registration
 export const apiTransformerTags = {
   ...restTags,
 }
 
-// Re-export individual tag modules for direct access if needed
 export { restTags } from './rest-tags'
diff --git a/src/article-api/liquid-renderers/rest-tags.ts b/src/article-api/liquid-renderers/rest-tags.ts
index 63b3ee52cd6f..e8121e40c9c2 100644
--- a/src/article-api/liquid-renderers/rest-tags.ts
+++ b/src/article-api/liquid-renderers/rest-tags.ts
@@ -7,10 +7,7 @@ import { createLogger } from '@/observability/logger'
 
 const logger = createLogger('article-api/liquid-renderers/rest-tags')
 
-/**
- * Custom Liquid tag for rendering REST API parameters
- * Usage: {% rest_parameter param %}
- */
+// Usage: {% rest_parameter param %}
 export class RestParameter {
   private paramName: string
 
@@ -56,10 +53,7 @@ export class RestParameter {
   }
 }
 
-/**
- * Custom Liquid tag for rendering REST API body parameters
- * Usage: {% rest_body_parameter param indent %}
- */
+// Usage: {% rest_body_parameter param indent %}
 export class RestBodyParameter {
   constructor(
     token: TagToken,
@@ -67,7 +61,6 @@ export class RestBodyParameter {
     liquid: Liquid,
     private liquidContext?: LiquidContext,
   ) {
-    // Parse arguments - param name and optional indent level
     const args = token.args.trim().split(/\s+/)
     this.param = args[0]
     this.indent = args[1] ? parseInt(args[1]) : 0
@@ -106,7 +99,6 @@ export class RestBodyParameter {
       lines.push(`${prefix}  Can be one of: ${param.enum.map((v) => `\`${v}\``).join(', ')}`)
     }
 
-    // Handle nested parameters
     if (param.childParamsGroups && param.childParamsGroups.length > 0) {
       for (const childGroup of param.childParamsGroups) {
         lines.push(await renderChildParameter(childGroup, context, indent + 1))
@@ -117,10 +109,7 @@ export class RestBodyParameter {
   }
 }
 
-/**
- * Custom Liquid tag for rendering REST API status codes
- * Usage: {% rest_status_code statusCode %}
- */
+// Usage: {% rest_status_code statusCode %}
 export class RestStatusCode {
   private statusCodeName: string
 
@@ -158,9 +147,6 @@ export class RestStatusCode {
   }
 }
 
-/**
- * Helper function to render child parameters recursively
- */
 async function renderChildParameter(
   param: ChildParameter,
   context: Context,
@@ -186,7 +172,6 @@ async function renderChildParameter(
     lines.push(`${prefix}  Can be one of: ${param.enum.map((v: string) => `\`${v}\``).join(', ')}`)
   }
 
-  // Recursively handle nested parameters
   if (param.childParamsGroups && param.childParamsGroups.length > 0) {
     for (const child of param.childParamsGroups) {
       lines.push(await renderChildParameter(child, context, indent + 1))
@@ -196,9 +181,6 @@ async function renderChildParameter(
   return lines.join('\n')
 }
 
-/**
- * Helper function to convert HTML to markdown
- */
 async function htmlToMarkdown(html: string, context: Context): Promise<string> {
   if (!html) return ''
 
@@ -215,12 +197,10 @@ async function htmlToMarkdown(html: string, context: Context): Promise<string> {
     if (process.env.NODE_ENV !== 'production') {
       throw error
     }
-    // Fallback to simple text extraction
     return fastTextOnly(html)
   }
 }
 
-// Export tag names for registration
 export const restTags = {
   rest_parameter: RestParameter,
   rest_body_parameter: RestBodyParameter,
diff --git a/src/article-api/middleware/article-body.ts b/src/article-api/middleware/article-body.ts
index cae5e7f003b8..ce0c6717c341 100644
--- a/src/article-api/middleware/article-body.ts
+++ b/src/article-api/middleware/article-body.ts
@@ -11,10 +11,7 @@ import { normalizeRenderedMarkdown } from '@/article-api/lib/normalize-markdown'
 import { allVersions } from '@/versions/lib/all-versions'
 import type { Page } from '@/types'
 
-/**
- * Creates a mocked rendering request and contextualizes it.
- * This is used to prepare a request for rendering pages in markdown format.
- */
+// Creates a mocked rendering request, contextualized for rendering a page as markdown.
 async function createContextualizedRenderingRequest(pathname: string, page: Page) {
   const mockedContext: Context = {}
   const renderingReq = {
@@ -52,7 +49,6 @@ export async function getArticleBody(req: ExtendedRequestWithPageInfo) {
   if (archived?.isArchived)
     throw new Error(`Page ${pathname} is archived and can't be rendered in markdown.`)
 
-  // Extract apiVersion from query params if provided
   const apiVersion = req.query.apiVersion as string | undefined
 
   // With the catch-all ArticleTransformer registered last,
@@ -60,7 +56,6 @@ export async function getArticleBody(req: ExtendedRequestWithPageInfo) {
   const transformer = transformerRegistry.findTransformer(page)
   if (!transformer) throw new Error(`No transformer found for page: ${pathname}`)
 
-  // Use the transformer
   const renderingReq = await createContextualizedRenderingRequest(pathname, page)
 
   // Determine the API version to use (provided or latest)
@@ -68,7 +63,6 @@ export async function getArticleBody(req: ExtendedRequestWithPageInfo) {
   const currentVersion = renderingReq.context.currentVersion
   let effectiveApiVersion = apiVersion
 
-  // Use latest version if not provided
   if (!effectiveApiVersion && currentVersion && allVersions[currentVersion]) {
     effectiveApiVersion = allVersions[currentVersion].latestApiVersion || undefined
   }
diff --git a/src/article-api/middleware/pagelist.ts b/src/article-api/middleware/pagelist.ts
index 295a18c49acf..a80978c481c4 100644
--- a/src/article-api/middleware/pagelist.ts
+++ b/src/article-api/middleware/pagelist.ts
@@ -35,15 +35,12 @@ router.get(
     defaultCacheControl(res)
 
     const response = {
-      // Simple list of all version strings
       versions: allVersionKeys,
-      // GHES-specific information
       ghesVersions: enterpriseServerReleases.supported,
       ghesLatest: enterpriseServerReleases.latest,
       ghesLatestStable: enterpriseServerReleases.latestStable,
       ghesReleaseCandidate: enterpriseServerReleases.releaseCandidate,
       ghesDeprecated: enterpriseServerReleases.deprecated,
-      // Full version details
       allVersions,
     }
 
@@ -77,9 +74,7 @@ router.get(
     )
 
     const response = {
-      // Simple list of language codes
       languages: languageKeys,
-      // Full language details (without redirectPatterns)
       allLanguages: sanitizedLanguages,
     }
 
@@ -142,10 +137,8 @@ router.get(
 
     const pages = req.context.pages
 
-    // the keys of `context.pages` are permalinks
     const keys = Object.keys(pages)
 
-    // we filter the permalinks to get only our target version and language
     const filteredPermalinks = keys.filter((key) =>
       versionMatcher(key, req.context!.currentVersion!, req.context!.currentLanguage!),
     )
diff --git a/src/article-api/middleware/validation.ts b/src/article-api/middleware/validation.ts
index 031b60704e49..eff2c9c842da 100644
--- a/src/article-api/middleware/validation.ts
+++ b/src/article-api/middleware/validation.ts
@@ -16,23 +16,19 @@ export const pagelistValidationMiddleware = (
   res: Response,
   next: NextFunction,
 ) => {
-  // get version from path, fallback to default version if it can't be resolved
   const versionFromPath = getVersionStringFromPath(req.path) || nonEnterpriseDefaultVersion
 
-  // in the rare case that this failed, probably won't be reached
+  // Defensive: getVersionStringFromPath falls back above, so this is unreachable.
   if (!versionFromPath)
     return res.status(400).json({ error: `Couldn't get version from the given path.` })
 
-  // get the language from path, fallback to english if it can't be resolved
   const langFromPath = getLangFromPath(req.path) || 'en'
 
-  // in the rare case that the language fallback failed
   if (!langFromPath)
     return res.status(400).json({
       error: `Couldn't get language from the from the given path.`,
     })
 
-  // set the version and language in the context, we'll use it later
   req.context!.currentVersion = versionFromPath
   req.context!.currentLanguage = langFromPath
   return next()
@@ -96,7 +92,7 @@ export const pageValidationMiddleware = (
     pathname = `/${req.context.currentLanguage}`
   }
 
-  // Initialize archived property to avoid it being undefined
+  // Initialized so downstream readers never see undefined.
   req.pageinfo.archived = { isArchived: false }
 
   if (!(pathname in req.context.pages)) {
@@ -133,24 +129,20 @@ export const apiVersionValidationMiddleware = (
 ) => {
   const apiVersion = req.query.apiVersion as string | string[] | undefined
 
-  // If no apiVersion is provided, continue (it will default to latest)
   if (!apiVersion) {
     return next()
   }
 
-  // Validate apiVersion is a single string, not an array
   if (Array.isArray(apiVersion)) {
     return res.status(400).json({ error: "Multiple 'apiVersion' keys" })
   }
 
-  // Get the version from the pathname query parameter
   const pathname = req.pageinfo?.pathname || (req.query.pathname as string)
   if (!pathname) {
     // This should not happen as pathValidationMiddleware runs first
     throw new Error('pathname not available for apiVersion validation')
   }
 
-  // Extract version from the pathname
   const currentVersion = getVersionStringFromPath(pathname) || nonEnterpriseDefaultVersion
   const versionInfo = allVersions[currentVersion]
 
@@ -160,7 +152,6 @@ export const apiVersionValidationMiddleware = (
 
   const validApiVersions = versionInfo.apiVersions || []
 
-  // If this version has API versioning, validate the provided version
   if (validApiVersions.length > 0 && !validApiVersions.includes(apiVersion)) {
     return res.status(400).json({
       error: `Invalid apiVersion '${apiVersion}' for ${currentVersion}. Valid API versions are: ${validApiVersions.join(', ')}`,
diff --git a/src/article-api/scripts/generate-api-docs.ts b/src/article-api/scripts/generate-api-docs.ts
index ba1b64c5f83d..081a72799d09 100644
--- a/src/article-api/scripts/generate-api-docs.ts
+++ b/src/article-api/scripts/generate-api-docs.ts
@@ -11,23 +11,18 @@ type ApiDoc = {
 }
 
 function main({ sources, outputPath }: { sources: string[]; outputPath: string }): void {
-  // Extract API documentation comments from all source files
   const allDocs = sources.flatMap((sourcePath) => extractApiDocs(sourcePath))
 
-  // Generate markdown
   const markdown = generateMarkdown(allDocs)
 
-  // Update README
   updateReadme(outputPath, markdown)
 
   console.log('API documentation generated successfully!')
 }
 
-// Extract API docs from comments in the file
 function extractApiDocs(file: string): ApiDoc[] {
   const apiDocs: ApiDoc[] = []
 
-  // get the content from the api routes
   const content = readFileSync(file, 'utf8')
 
   // Get the router method definitions with JSDOC-style comments
@@ -40,15 +35,13 @@ function extractApiDocs(file: string): ApiDoc[] {
     const method = match[2]
     const path = match[3]
 
-    // The description is first line of the comment
     const description = commentBlock
       .trim()
       .split('\n')[0]
       .trim()
       .replace(/^\*\s*/, '')
 
-    // Grab the other elements from the comment
-    // we currently support: params, returns, examples, throws
+    // We currently support params, returns, examples, and throws.
     const params = extractParams(commentBlock)
     const returns = extractReturns(commentBlock)
     const examples = extractExample(commentBlock)
@@ -82,7 +75,6 @@ function extractThrows(commentBlock: string): string[] {
   return throws
 }
 
-// Extract parameters from comment block
 function extractParams(commentBlock: string): string[] {
   const paramRegex = /@param\s+{([^}]+)}\s+([^\s]+)\s+([^\n]+)/g
   const params: string[] = []
@@ -98,7 +90,6 @@ function extractParams(commentBlock: string): string[] {
   return params
 }
 
-// Extract return info from comment block
 function extractReturns(commentBlock: string): string {
   const returnMatch = commentBlock.match(/@returns\s+{([^}]+)}\s+([^\n]+)/)
   if (returnMatch) {
@@ -109,7 +100,6 @@ function extractReturns(commentBlock: string): string {
   return ''
 }
 
-// Extract example from comment block
 function extractExample(commentBlock: string): string {
   const exampleMatch = commentBlock.match(/@example\b([\s\S]*?)(?=\s*\*\s*@|\s*\*\/|$)/)
   if (exampleMatch) {
@@ -123,7 +113,6 @@ function extractExample(commentBlock: string): string {
   return ''
 }
 
-// Generate markdown from parsed documentation
 function generateMarkdown(apiDocs: ApiDoc[]): string {
   let markdown = '## Reference: API endpoints\n\n'
 
@@ -157,14 +146,12 @@ function generateMarkdown(apiDocs: ApiDoc[]): string {
   return markdown
 }
 
-// Update README with generated documentation
 function updateReadme(readmePath: string, markdown: string): void {
   if (existsSync(readmePath)) {
     let readme = readFileSync(readmePath, 'utf8')
 
     const placeholderComment = `<!-- API reference docs automatically generated, do not edit below this comment -->`
 
-    // Replace API documentation section, or append to end
     if (readme.includes(placeholderComment)) {
       const pattern = new RegExp(`${placeholderComment}[\\s\\S]*`, 'g')
       readme = readme.replace(pattern, `${placeholderComment}\n${markdown}`)

From 140d7958269d0209f33ed65196291abd48d1580e Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:16:36 +0000
Subject: [PATCH 02/16] Trim excessive comments in src/content-render/scripts
 (#63277)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 .../scripts/add-content-type.ts               |  4 -
 src/content-render/scripts/cta-builder.ts     | 41 +---------
 src/content-render/scripts/liquid-tags.ts     | 78 +------------------
 .../scripts/move-by-content-type.ts           | 45 +----------
 src/content-render/scripts/move-content.ts    |  4 +-
 .../reusables-cli/find/potential-uses.ts      |  2 -
 .../scripts/reusables-cli/find/used.ts        |  1 -
 .../scripts/reusables-cli/shared.ts           |  3 -
 .../scripts/update-filepaths.ts               | 16 +---
 9 files changed, 7 insertions(+), 187 deletions(-)

diff --git a/src/content-render/scripts/add-content-type.ts b/src/content-render/scripts/add-content-type.ts
index 588b484bdaf0..f6286ea7b4a2 100644
--- a/src/content-render/scripts/add-content-type.ts
+++ b/src/content-render/scripts/add-content-type.ts
@@ -107,7 +107,6 @@ function processFile(filePath: string, scriptOptions: ScriptOptions) {
     return { processed: true, updated: false }
   }
 
-  // Check if we're actually changing an existing contentType
   const isChangingContentType = data.contentType && data.contentType !== newContentType
   const isAddingContentType = !data.contentType
 
@@ -119,7 +118,6 @@ function processFile(filePath: string, scriptOptions: ScriptOptions) {
     console.log(`Adding contentType '${newContentType}' on ${relativePath}`)
   }
 
-  // Only update if there's actually a change needed
   if (isChangingContentType || isAddingContentType) {
     data.contentType = newContentType
   } else {
@@ -127,7 +125,6 @@ function processFile(filePath: string, scriptOptions: ScriptOptions) {
     return { processed: true, updated: false }
   }
 
-  // Write the file back
   fs.writeFileSync(
     filePath,
     frontmatter.stringify(
@@ -183,7 +180,6 @@ function determineContentType(relativePath: string): string {
     return LANDING_TYPE
   }
 
-  // Classify anything else as 'other'.
   return OTHER_TYPE
 }
 
diff --git a/src/content-render/scripts/cta-builder.ts b/src/content-render/scripts/cta-builder.ts
index bd633c63dbb6..96ca90b65f00 100644
--- a/src/content-render/scripts/cta-builder.ts
+++ b/src/content-render/scripts/cta-builder.ts
@@ -31,7 +31,6 @@ type CTASchemaProperties = {
   [K in keyof CTAParams]-?: CTASchemaProperty
 }
 
-// Conversion mappings from old CTA format to new schema
 const ctaToTypeMapping: Record<string, string> = {
   'GHEC trial': 'trial',
   'Copilot trial': 'trial',
@@ -51,18 +50,15 @@ const ctaToPlanMapping: Record<string, string> = {
   'GHEC trial': 'enterprise',
 }
 
-// Keywords that suggest a button context vs inline text link
 const buttonKeywords = ['landing', 'signup', 'download', 'trial']
 
 const program = new Command()
 
-// CLI setup
 program
   .name('cta-builder')
   .description('Create a properly formatted Call-to-Action URL with tracking parameters.')
   .version('1.0.0')
 
-// Add conversion command
 program
   .command('convert')
   .description('Convert old CTA URLs to new schema format')
@@ -72,7 +68,6 @@ program
     convertUrls(options)
   })
 
-// Add validation command
 program
   .command('validate')
   .description('Validate a CTA URL against the schema')
@@ -81,7 +76,6 @@ program
     validateUrl(options)
   })
 
-// Add programmatic build command
 program
   .command('build')
   .description('Build a CTA URL programmatically with flags (outputs URL only)')
@@ -94,7 +88,6 @@ program
     buildProgrammaticCTA(options)
   })
 
-// Default to interactive mode
 program.action(() => {
   interactiveBuilder()
 })
@@ -104,7 +97,6 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   program.parse()
 }
 
-// Helper function to select from lettered options
 async function selectFromOptions(
   paramName: string,
   message: string,
@@ -139,7 +131,6 @@ async function selectFromOptions(
   }
 }
 
-// Helper function to confirm yes/no
 async function confirmChoice(
   message: string,
   promptFn: (question: string) => Promise<string>,
@@ -161,7 +152,6 @@ async function confirmChoice(
   }
 }
 
-// Extract CTA parameters from a URL
 function extractCTAParams(url: string): CTAParams {
   const urlObj = new URL(url)
   const ctaParams: CTAParams = {}
@@ -224,7 +214,6 @@ function validateCTAParams(params: CTAParams): { isValid: boolean; errors: strin
   }
 }
 
-// Build URL with CTA parameters
 function buildCTAUrl(baseUrl: string, params: CTAParams): string {
   const url = new URL(baseUrl)
 
@@ -237,17 +226,15 @@ function buildCTAUrl(baseUrl: string, params: CTAParams): string {
   return url.toString()
 }
 
-// Convert old CTA URL to new schema format
 export function convertOldCTAUrl(oldUrl: string): { newUrl: string; notes: string[] } {
   const notes: string[] = []
 
   try {
     const url = new URL(oldUrl)
 
-    // Build new parameters
     const newParams: CTAParams = {}
 
-    // First, check if any of the new params already exist, and preserve those if so
+    // Preserve any new-style params that are already on the URL.
     for (const [key, value] of url.searchParams.entries()) {
       for (const param of Object.keys(ctaSchema.properties)) {
         if (key === param && key in ctaSchema.properties) {
@@ -264,17 +251,14 @@ export function convertOldCTAUrl(oldUrl: string): { newUrl: string; notes: strin
       }
     }
 
-    // Try to convert old params to new params
     const refCta = url.searchParams.get('ref_cta') || ''
     const refLoc = url.searchParams.get('ref_loc') || ''
 
-    // Map ref_product
     if (!newParams.ref_product) {
       newParams.ref_product = inferProductFromUrl(oldUrl, refCta)
       notes.push(`-  Missing ref_product - made an inference, manually update if needed`)
     }
 
-    // Map ref_type
     if (!newParams.ref_type) {
       newParams.ref_type = ctaToTypeMapping[refCta] || 'engagement'
       if (!ctaToTypeMapping[refCta]) {
@@ -282,13 +266,11 @@ export function convertOldCTAUrl(oldUrl: string): { newUrl: string; notes: strin
       }
     }
 
-    // Map ref_style
     if (!newParams.ref_style) {
       newParams.ref_style = inferStyleFromContext(refLoc)
       notes.push(`-  Missing ref_style - made an inference, manually update if needed`)
     }
 
-    // Map ref_plan (optional)
     if (!newParams.ref_plan) {
       if (ctaToPlanMapping[refCta]) {
         newParams.ref_plan = ctaToPlanMapping[refCta]
@@ -298,12 +280,10 @@ export function convertOldCTAUrl(oldUrl: string): { newUrl: string; notes: strin
     // Build new URL - preserve all existing parameters except old ref_ parameters
     const newUrl = new URL(url.toString())
 
-    // Remove old CTA parameters
     newUrl.searchParams.delete('ref_cta')
     newUrl.searchParams.delete('ref_loc')
     newUrl.searchParams.delete('ref_page')
 
-    // Add new CTA parameters
     for (const [key, value] of Object.entries(newParams)) {
       if (value) {
         newUrl.searchParams.set(key, value)
@@ -343,7 +323,6 @@ function inferProductFromUrl(url: string, refCta: string): string {
   } catch {
     // Fallback if url isn't valid: leave hostname empty
   }
-  // Strict hostname check for desktop.github.com
   if (hostname === 'desktop.github.com' || refCta.includes('desktop')) {
     return 'desktop'
   }
@@ -361,7 +340,6 @@ function inferProductFromUrl(url: string, refCta: string): string {
   ) {
     return 'ghec'
   }
-  // Default fallback
   return 'copilot'
 }
 
@@ -372,15 +350,12 @@ function inferStyleFromContext(refLoc: string): string {
   return isButton ? 'button' : 'text'
 }
 
-// Interactive CTA builder
 async function interactiveBuilder(): Promise<void> {
-  // Create readline interface for interactive mode
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
   })
 
-  // Helper function to prompt user (scoped to this function)
   function prompt(question: string): Promise<string> {
     return new Promise((resolve) => {
       rl.question(question, (answer) => {
@@ -392,7 +367,6 @@ async function interactiveBuilder(): Promise<void> {
   try {
     console.log(chalk.blue.bold('🚀 Guided CTA URL builder\n'))
 
-    // Get base URL with validation
     let baseUrl = ''
     while (!baseUrl) {
       const input = await prompt('Enter the base URL (e.g., https://github.com/features/copilot): ')
@@ -406,7 +380,6 @@ async function interactiveBuilder(): Promise<void> {
 
     const params: CTAParams = {}
 
-    // Required parameters
     console.log(chalk.white(`\nRequired parameters:`))
     const schemaProps = ctaSchema.properties as CTASchemaProperties
 
@@ -442,7 +415,6 @@ async function interactiveBuilder(): Promise<void> {
       }
     }
 
-    // Validate parameters
     const validation = validateCTAParams(params)
 
     if (!validation.isValid) {
@@ -454,7 +426,6 @@ async function interactiveBuilder(): Promise<void> {
       return
     }
 
-    // Build and display URL
     const ctaUrl = buildCTAUrl(baseUrl, params)
 
     console.log(chalk.green('\n✅ CTA URL generated successfully!'))
@@ -477,7 +448,6 @@ async function interactiveBuilder(): Promise<void> {
   }
 }
 
-// Convert URLs command handler
 async function convertUrls(options: { url?: string; quiet?: boolean }): Promise<void> {
   try {
     if (!options.quiet) {
@@ -540,7 +510,6 @@ async function convertUrls(options: { url?: string; quiet?: boolean }): Promise<
   // The convert command doesn't use readline, so script should exit naturally
 }
 
-// Validate URLs command handler
 async function validateUrl(options: { url?: string }): Promise<void> {
   try {
     console.log(chalk.blue.bold('CTA URL validator'))
@@ -549,7 +518,6 @@ async function validateUrl(options: { url?: string }): Promise<void> {
       console.log(chalk.white('\nValidating URL:'))
       console.log(chalk.gray(options.url))
 
-      // Extract CTA parameters from URL
       let ctaParams: CTAParams
       try {
         ctaParams = extractCTAParams(options.url)
@@ -558,7 +526,6 @@ async function validateUrl(options: { url?: string }): Promise<void> {
         return
       }
 
-      // Check if URL has any CTA parameters
       if (Object.keys(ctaParams).length === 0) {
         console.log(chalk.yellow('\nℹ️ No CTA parameters found in URL'))
         return
@@ -598,7 +565,6 @@ async function validateUrl(options: { url?: string }): Promise<void> {
   }
 }
 
-// Programmatic build command handler
 async function buildProgrammaticCTA(options: {
   url: string
   product: string
@@ -607,7 +573,6 @@ async function buildProgrammaticCTA(options: {
   plan?: string
 }): Promise<void> {
   try {
-    // Validate base URL
     let baseUrl: string
     try {
       baseUrl = new URL(options.url).toString()
@@ -618,19 +583,16 @@ async function buildProgrammaticCTA(options: {
       process.exit(1)
     }
 
-    // Build CTA parameters object
     const params: CTAParams = {
       ref_product: options.product,
       ref_type: options.type,
       ref_style: options.style,
     }
 
-    // Add optional parameters
     if (options.plan) {
       params.ref_plan = options.plan
     }
 
-    // Validate parameters against schema
     const validation = validateCTAParams(params)
     if (!validation.isValid) {
       // Output validation errors to stderr and exit with error code
@@ -640,7 +602,6 @@ async function buildProgrammaticCTA(options: {
       process.exit(1)
     }
 
-    // Build and output the URL (stdout only)
     const ctaUrl = buildCTAUrl(baseUrl, params)
     console.log(ctaUrl)
   } catch (error) {
diff --git a/src/content-render/scripts/liquid-tags.ts b/src/content-render/scripts/liquid-tags.ts
index e15a3e3ab6f4..e24fdf6cfc73 100644
--- a/src/content-render/scripts/liquid-tags.ts
+++ b/src/content-render/scripts/liquid-tags.ts
@@ -11,7 +11,6 @@ import path from 'path'
 import { load, dump } from 'js-yaml'
 import chalk from 'chalk'
 
-// Type definitions
 interface ExpandOptions {
   paths: string[]
   verbose?: boolean
@@ -30,7 +29,6 @@ interface LiquidReference {
   endIndex: number
 }
 
-// Constants
 const ROOT = process.env.ROOT || '.'
 const DATA_ROOT = path.resolve(path.join(ROOT, 'data'))
 const REUSABLES_ROOT = path.join(DATA_ROOT, 'reusables')
@@ -43,14 +41,9 @@ function getErrorMessage(error: unknown): string {
 // Regex pattern to match expanded content blocks
 const EXPANDED_PATTERN = /<!-- begin (reusable|variable)s\.([^>]+) -->(.+?)<!-- end \1s\.\2 -->/gs
 
-/**
- * Get the file path for a data reference
- *
- * Validates and normalizes the incoming dataPath to prevent path traversal
- * and ensure the final resolved path remains within the expected root.
- */
+// Validates and normalizes the incoming dataPath to prevent path traversal
+// and ensure the final resolved path remains within the expected root.
 function getDataFilePath(type: 'reusable' | 'variable', dataPath: string): string {
-  // Basic validation of the raw dataPath
   if (path.isAbsolute(dataPath)) {
     throw new Error(`Invalid ${type} data path: absolute paths are not allowed: ${dataPath}`)
   }
@@ -89,9 +82,6 @@ function getDataFilePath(type: 'reusable' | 'variable', dataPath: string): strin
   }
 }
 
-/**
- * Convert a file path back to data path format (for consistent verbose output)
- */
 function convertFilePathToDataPath(filePath: string): string {
   const normalizedPath = path.normalize(filePath)
 
@@ -134,9 +124,6 @@ program
 
 program.parse()
 
-/**
- * Get allowed types based on command options
- */
 function getAllowedTypes(options: ExpandOptions): Array<'reusable' | 'variable'> {
   if (options.reusablesOnly && options.variablesOnly) {
     console.log(
@@ -155,13 +142,9 @@ function getAllowedTypes(options: ExpandOptions): Array<'reusable' | 'variable'>
     return ['variable']
   }
 
-  // Default: process both types
   return ['reusable', 'variable']
 }
 
-/**
- * Expand Liquid data references in content files
- */
 async function expandReferences(options: ExpandOptions): Promise<void> {
   const { paths, verbose, markers, shallow } = options
   // markers will be true by default, false when --no-markers is used
@@ -217,7 +200,6 @@ async function expandReferences(options: ExpandOptions): Promise<void> {
           }
         }
 
-        // Check for remaining references
         const remainingRefs = findLiquidReferences(expandedContent, allowedTypes)
         hasRemainingRefs = remainingRefs.length > 0
 
@@ -278,9 +260,6 @@ async function expandReferences(options: ExpandOptions): Promise<void> {
   }
 }
 
-/**
- * Restore content by restoring original Liquid statements from HTML comments
- */
 async function restoreReferences(options: ExpandOptions): Promise<void> {
   const { paths, verbose } = options
   const allowedTypes = getAllowedTypes(options)
@@ -306,7 +285,6 @@ async function restoreReferences(options: ExpandOptions): Promise<void> {
 
       const content = fs.readFileSync(filePath, 'utf-8')
 
-      // Check for content edits before restoring
       const hasEdits = await detectContentEdits(content, verbose, allowedTypes)
       if (hasEdits) {
         console.log(
@@ -361,9 +339,6 @@ async function restoreReferences(options: ExpandOptions): Promise<void> {
   }
 }
 
-/**
- * Expand all Liquid data references in file content
- */
 async function expandFileContent(
   content: string,
   filePath: string,
@@ -421,14 +396,10 @@ async function expandFileContent(
     }
   }
 
-  // Note: Remaining reference detection is now handled in expandReferences function for recursive mode
-
+  // expandReferences handles remaining-reference detection in recursive mode.
   return expandedContent
 }
 
-/**
- * Detect if expanded content has been edited by comparing with original data
- */
 async function detectContentEdits(
   content: string,
   verbose?: boolean,
@@ -441,7 +412,6 @@ async function detectContentEdits(
     const [, type, dataPath, resolvedContent] = match
     const refType = type as 'reusable' | 'variable'
 
-    // Only check if this type is allowed
     if (!allowedTypes || allowedTypes.includes(refType)) {
       try {
         // Load the original content from data files
@@ -478,9 +448,6 @@ async function detectContentEdits(
   return hasEdits
 }
 
-/**
- * Load data value from file system (helper for edit detection)
- */
 function loadDataValue(type: 'reusable' | 'variable', dataPath: string): string | null {
   try {
     const targetPath = getDataFilePath(type, dataPath)
@@ -498,7 +465,6 @@ function loadDataValue(type: 'reusable' | 'variable', dataPath: string): string
       const yamlContent = fs.readFileSync(targetPath, 'utf8')
       const data = load(yamlContent) as Record<string, unknown>
 
-      // Navigate to the nested property
       const pathParts = dataPath.split('.')
       let current: unknown = data
       for (let i = 1; i < pathParts.length; i++) {
@@ -517,9 +483,6 @@ function loadDataValue(type: 'reusable' | 'variable', dataPath: string): string
   return null
 }
 
-/**
- * Restore content by restoring original Liquid statements
- */
 function restoreFileContent(
   content: string,
   verbose?: boolean,
@@ -528,7 +491,6 @@ function restoreFileContent(
   return content.replace(EXPANDED_PATTERN, (match, type, dataPath) => {
     const refType = type as 'reusable' | 'variable'
 
-    // Only restore if this type is allowed
     if (!allowedTypes || allowedTypes.includes(refType)) {
       const originalLiquid = `{% data ${type}s.${dataPath} %}`
 
@@ -539,15 +501,10 @@ function restoreFileContent(
       return originalLiquid
     }
 
-    // Return unchanged if type is not allowed
     return match
   })
 }
 
-/**
- * Update data files with content from expanded blocks
- * Returns array of file paths that were updated
- */
 function updateDataFiles(
   filePath: string,
   verbose?: boolean,
@@ -564,7 +521,6 @@ function updateDataFiles(
     return []
   }
 
-  // Group updates by file path
   const updatesByFile = new Map<string, string[]>()
   for (const update of updates) {
     const key = `${update.type}:${update.path}`
@@ -576,7 +532,6 @@ function updateDataFiles(
 
   const updatedFiles: string[] = []
 
-  // Apply updates to each data file
   for (const [key, contents] of updatesByFile) {
     const [type, dataPath] = key.split(':')
     const targetFilePath = applyDataUpdates(
@@ -594,9 +549,6 @@ function updateDataFiles(
   return updatedFiles
 }
 
-/**
- * Extract data updates from expanded content blocks
- */
 function extractDataUpdates(
   content: string,
   allowedTypes?: Array<'reusable' | 'variable'>,
@@ -608,13 +560,11 @@ function extractDataUpdates(
     const [, type, dataPath, resolvedContent] = match
     const refType = type as 'reusable' | 'variable'
 
-    // Only include if this type is allowed
     if (!allowedTypes || allowedTypes.includes(refType)) {
       // Check if this content was actually changed before including it
       try {
         const originalContent = loadDataValue(refType, dataPath.trim())
         if (originalContent !== null && resolvedContent.trim() !== originalContent.trim()) {
-          // Only add to updates if content was actually changed
           updates.push({
             type: refType,
             path: dataPath.trim(),
@@ -635,10 +585,6 @@ function extractDataUpdates(
   return updates
 }
 
-/**
- * Apply updates to a specific data file
- * Returns the file path if file was updated, null otherwise
- */
 function applyDataUpdates(
   type: 'reusable' | 'variable',
   dataPath: string,
@@ -648,7 +594,6 @@ function applyDataUpdates(
 ): string | null {
   const targetPath = getDataFilePath(type, dataPath)
 
-  // Check if file exists
   if (!fs.existsSync(targetPath)) {
     if (verbose) {
       console.log(chalk.red(`  Error: Data file not found: ${targetPath}`))
@@ -701,7 +646,6 @@ function applyDataUpdates(
       const yamlContent = fs.readFileSync(targetPath, 'utf8')
       const data = load(yamlContent) as Record<string, unknown>
 
-      // Navigate to the nested property
       const pathParts = dataPath.split('.')
       const propertyPath = pathParts.slice(1) // Skip the file name
 
@@ -713,7 +657,6 @@ function applyDataUpdates(
         current = current[propertyPath[i]] as Record<string, unknown>
       }
 
-      // Update the final property
       const finalKey = propertyPath[propertyPath.length - 1]
       if (contents.length > 1) {
         console.log(
@@ -728,7 +671,6 @@ function applyDataUpdates(
       const finalYaml =
         hasTrailingNewline && !yamlOutput.endsWith('\n') ? `${yamlOutput}\n` : yamlOutput
 
-      // Write back to file
       fs.writeFileSync(targetPath, finalYaml)
       if (verbose) {
         console.log(chalk.green(`  Updated: ${type}s.${dataPath}`))
@@ -743,9 +685,6 @@ function applyDataUpdates(
   }
 }
 
-/**
- * Find all Liquid data references in content
- */
 function findLiquidReferences(
   content: string,
   allowedTypes?: Array<'reusable' | 'variable'>,
@@ -761,7 +700,6 @@ function findLiquidReferences(
     const [original, type, dataPath] = match
     const refType = type.slice(0, -1) as 'reusable' | 'variable' // Remove 's' from end
 
-    // Only include if this type is allowed
     if (types.includes(refType)) {
       references.push({
         original,
@@ -776,9 +714,6 @@ function findLiquidReferences(
   return references
 }
 
-/**
- * Resolve a single Liquid data reference to its content
- */
 async function resolveLiquidReference(
   ref: LiquidReference,
   verbose?: boolean,
@@ -798,9 +733,6 @@ async function resolveLiquidReference(
   return null
 }
 
-/**
- * Resolve a reusable reference by reading the markdown file
- */
 async function resolveReusable(reusablePath: string, verbose?: boolean): Promise<string | null> {
   const filePath = getDataFilePath('reusable', reusablePath)
 
@@ -826,9 +758,6 @@ async function resolveReusable(reusablePath: string, verbose?: boolean): Promise
   }
 }
 
-/**
- * Resolve a variable reference by reading from YAML files
- */
 async function resolveVariable(variablePath: string, verbose?: boolean): Promise<string | null> {
   const pathParts = variablePath.split('.')
 
@@ -866,7 +795,6 @@ async function resolveVariable(variablePath: string, verbose?: boolean): Promise
       }
     }
 
-    // Convert value to string
     if (typeof value === 'string') {
       return value
     } else if (value !== null && value !== undefined) {
diff --git a/src/content-render/scripts/move-by-content-type.ts b/src/content-render/scripts/move-by-content-type.ts
index c64ef0ed27fc..e7773d92d881 100644
--- a/src/content-render/scripts/move-by-content-type.ts
+++ b/src/content-render/scripts/move-by-content-type.ts
@@ -26,7 +26,6 @@ const contentTypeToDir = (contentType: string): string => {
 
 const validContentTypeDirs = new Set(CONTENT_TYPES.map(contentTypeToDir))
 
-// Helper: Should we skip this index.md file from processing?
 function shouldSkipIndexFile(filePath: string): boolean {
   const relativePath = path.relative(process.cwd(), filePath)
   const parts = relativePath.split(path.sep)
@@ -44,17 +43,14 @@ function shouldSkipIndexFile(filePath: string): boolean {
   return false
 }
 
-// Helper: Calculate target directory for a file
 function calculateTarget(filePath: string, contentType: string, productDir: string) {
   const relativePath = path.relative(process.cwd(), filePath)
   const parts = relativePath.split(path.sep)
   const contentIndex = parts.indexOf('content')
   const fileName = path.basename(filePath)
 
-  // Determine target content-type directory
   const targetContentType = contentTypeToDir(contentType)
 
-  // Calculate target path
   if (targetContentType === 'how-tos') {
     // Preserve subdirectory structure for how-tos
     const pathAfterProduct = parts.slice(contentIndex + 2, -1)
@@ -85,9 +81,7 @@ program
   .description('Reorganize content files into subdirectories based on their contentType property')
   .argument('[paths...]', 'Content paths to process')
   .action(async (paths: string[]) => {
-    // ====================
-    // 1. GATHER FILES
-    // ====================
+    // Gather files.
     const filesToProcess: string[] = []
     if (paths?.length > 0) {
       for (const p of paths) {
@@ -104,9 +98,6 @@ program
 
     console.log(chalk.white(`Processing ${filesToProcess.length} files...\n`))
 
-    // ====================
-    // 2. ANALYZE & PLAN MOVES
-    // ====================
     console.log(chalk.white('Analyzing files...\n'))
 
     const filesToMove: FileMove[] = []
@@ -125,7 +116,6 @@ program
           continue
         }
 
-        // Read and validate contentType
         const fileContent = await fs.readFile(filePath, 'utf-8')
         const { data } = readFrontmatter(fileContent)
 
@@ -145,7 +135,6 @@ program
           continue
         }
 
-        // Validate contentType
         if (!CONTENT_TYPES.includes(contentType)) {
           skipped.push({ file: relativePath, reason: `Invalid contentType: ${contentType}` })
           console.log(
@@ -154,7 +143,6 @@ program
           continue
         }
 
-        // Get product directory
         if (contentIndex === -1 || contentIndex + 1 >= parts.length) {
           console.log(
             chalk.yellow(`⚠ Skipping ${relativePath}: Cannot determine product directory`),
@@ -168,13 +156,10 @@ program
 
         if (contentType === 'rai') productsWithRai.add(productName)
 
-        // Calculate target
         const { targetDir, targetPath } = calculateTarget(filePath, contentType, productDir)
 
-        // Skip if already in correct location
         if (path.dirname(filePath) === targetDir) continue
 
-        // Skip if target exists
         try {
           await fs.access(targetPath)
           skipped.push({ file: relativePath, reason: 'Target already exists' })
@@ -184,7 +169,6 @@ program
           // Good, doesn't exist
         }
 
-        // Track this move
         filesToMove.push({ filePath, targetDir, targetPath, contentType })
 
         const relativeTargetDir = path.relative(process.cwd(), targetDir)
@@ -209,9 +193,6 @@ program
       }
     }
 
-    // ====================
-    // 3. ENSURE STANDARD DIRECTORIES
-    // ====================
     console.log(chalk.white('Ensuring standard content-type directories exist...\n'))
 
     // Add standard content-type directories for each affected product
@@ -236,9 +217,6 @@ program
       }
     }
 
-    // ====================
-    // 4. CREATE PLACEHOLDERS
-    // ====================
     console.log(chalk.white('Creating placeholder index.md files...\n'))
 
     const newPlaceholders: string[] = []
@@ -295,9 +273,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // ====================
-    // 5. GENERATE INTROS
-    // ====================
     if (newPlaceholders.length > 0) {
       console.log(chalk.white('\nGenerating intros for placeholder files...\n'))
 
@@ -337,9 +312,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // ====================
-    // 6. MOVE FILES
-    // ====================
     console.log(chalk.white('\nMoving files...\n'))
 
     const moved: Array<{ file: string; from: string; to: string }> = []
@@ -397,7 +369,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // Move regular files
     for (const file of regularFiles) {
       try {
         await fs.mkdir(file.targetDir, { recursive: true })
@@ -427,7 +398,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // Delete source subdirectory index files
     for (const sourcePath of indexFilesToDeleteLater) {
       try {
         await fs.unlink(sourcePath)
@@ -437,7 +407,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // Move top-level index files
     for (const file of topLevelIndexFiles) {
       try {
         await fs.mkdir(file.targetDir, { recursive: true })
@@ -462,9 +431,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // ====================
-    // 7. CLEANUP & UPDATE
-    // ====================
     console.log(
       chalk.white('\nCleaning up old directories and updating parent index.md files...\n'),
     )
@@ -498,7 +464,6 @@ contentType: ${placeholderContentType}
         console.log(chalk.yellow(`⚠ Could not read product directory ${productDir}: ${error}`))
       }
 
-      // Update product index.md
       const productIndexPath = path.join(productDir, 'index.md')
       try {
         const content = await fs.readFile(productIndexPath, 'utf-8')
@@ -507,7 +472,6 @@ contentType: ${placeholderContentType}
         if (data) {
           let updated = false
 
-          // Build children array
           const productRelativePath = path.relative(process.cwd(), productDir)
           const newChildren: string[] = []
           for (const ct of CONTENT_TYPES.map(contentTypeToDir)) {
@@ -520,7 +484,6 @@ contentType: ${placeholderContentType}
             updated = true
           }
 
-          // Add redirects for deleted directories
           const deletedPaths = deletedByProduct.get(productName) || []
           if (deletedPaths.length > 0) {
             if (!data.redirect_from) data.redirect_from = []
@@ -551,9 +514,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // ====================
-    // 8. SORT CHILDREN ARRAYS
-    // ====================
     console.log(chalk.white('\nSorting children arrays...\n'))
 
     for (const dirPath of targetDirs) {
@@ -612,9 +572,6 @@ contentType: ${placeholderContentType}
       }
     }
 
-    // ====================
-    // 9. SUMMARY
-    // ====================
     console.log(chalk.white(`\n${'='.repeat(60)}`))
     console.log(chalk.white('Summary:'))
     console.log(chalk.white(`  Moved: ${moved.length} files`))
diff --git a/src/content-render/scripts/move-content.ts b/src/content-render/scripts/move-content.ts
index 6bbdcb1a0635..004cb880363d 100755
--- a/src/content-render/scripts/move-content.ts
+++ b/src/content-render/scripts/move-content.ts
@@ -33,7 +33,6 @@ import escapeStringRegexp from 'escape-string-regexp'
 import fm from '@/frame/lib/frontmatter'
 import readFrontmatter from '@/frame/lib/read-frontmatter'
 
-// Type definitions
 interface MoveOptions {
   verbose: boolean
   undo: boolean
@@ -156,8 +155,7 @@ async function main(opts: MoveOptions, nameTuple: string[]) {
     if (!fs.existsSync(indexFilePath)) {
       throw new Error(`${oldPath} does not have an index.md file`)
     }
-    // Gather individual files by walking `oldPath` recursively
-    // The second argument is
+    // Gather individual files by walking `oldPath` recursively.
     const files = findFilesInFolder(oldPath, newPath, opts)
 
     // First take care of the `git mv` (or regular rename) part.
diff --git a/src/content-render/scripts/reusables-cli/find/potential-uses.ts b/src/content-render/scripts/reusables-cli/find/potential-uses.ts
index cb423a475038..c0827117caa9 100644
--- a/src/content-render/scripts/reusables-cli/find/potential-uses.ts
+++ b/src/content-render/scripts/reusables-cli/find/potential-uses.ts
@@ -26,7 +26,6 @@ export function findPotentialUses({
   const filesThatCouldUseReusable: FilesWithLineNumbers = []
   const filesThatCouldUseReusableSimilar: FilesWithSimilarity = []
 
-  // Read all content & data files into memory
   const allFileContents = allFilePaths.map((filePath) => {
     return {
       filePath,
@@ -69,7 +68,6 @@ export function findPotentialUses({
 
       const indices = findIndicesOfSubstringInString(reusableContents.trim(), fileContents)
       if (indices.length > 0) {
-        // Find line numbers of each index in fileContents
         const lineNumbers = indices.map((index) => fileContents.slice(0, index).split('\n').length)
 
         filesThatCouldUseReusable.push({
diff --git a/src/content-render/scripts/reusables-cli/find/used.ts b/src/content-render/scripts/reusables-cli/find/used.ts
index 589b87e12e6c..6f56c31512d6 100644
--- a/src/content-render/scripts/reusables-cli/find/used.ts
+++ b/src/content-render/scripts/reusables-cli/find/used.ts
@@ -33,7 +33,6 @@ export function findUsed(reusablePath: string, { absolute }: { absolute: boolean
 
     const indices = getIndicesOfLiquidVariable(reusableLiquidVar, fileContents)
     if (indices.length > 0) {
-      // Find line numbers of each index in fileContents
       const lineNumbers = indices.map((index) => fileContents.slice(0, index).split('\n').length)
 
       filesWithReusables.push({
diff --git a/src/content-render/scripts/reusables-cli/shared.ts b/src/content-render/scripts/reusables-cli/shared.ts
index 792f48828bdc..c04e24725d15 100644
--- a/src/content-render/scripts/reusables-cli/shared.ts
+++ b/src/content-render/scripts/reusables-cli/shared.ts
@@ -48,7 +48,6 @@ export function getAllContentFilePaths() {
   return [...allContentFiles, ...allDataFiles]
 }
 
-// Get the string that represents the reusable in the content files
 export function getReusableLiquidString(reusablePath: string): string {
   const relativePath = path.relative(reusablesDirectory, reusablePath)
   return `reusables.${relativePath.slice(0, -3).split('/').join('.')}`
@@ -73,7 +72,6 @@ export function getIndicesOfLiquidVariable(liquidVariable: string, fileContents:
   return indices
 }
 
-// Find the path to a reusable file.
 export function resolveReusablePath(reusablePath: string): string {
   // Try .md if extension is not provided
   if (!reusablePath.endsWith('.md') && !reusablePath.endsWith('.yml')) {
@@ -150,7 +148,6 @@ export function findSimilarSubStringInString(substr: string, str: string) {
     }
   }
 
-  // Normalize the similarity score
   return Math.round((similarityScore / substrSentences.length) * corpus.length)
 }
 
diff --git a/src/content-render/scripts/update-filepaths.ts b/src/content-render/scripts/update-filepaths.ts
index f86693010639..7760d5c7b441 100755
--- a/src/content-render/scripts/update-filepaths.ts
+++ b/src/content-render/scripts/update-filepaths.ts
@@ -101,13 +101,11 @@ async function processFile(
 
   const isDirectory = isDirectoryCheck(file)
 
-  // Assess the frontmatter and other conditions to determine if we want to process the path.
   const processPage: boolean = determineProcessStatus(data, isDirectory, scriptOptions)
   if (!processPage) return null
 
   let stringToSlugify: string = data.shortTitle || data.title
 
-  // Check if we need to process Liquid
   if (stringToSlugify.includes('{%')) {
     stringToSlugify = await renderContent(stringToSlugify, context, { textOnly: true })
   }
@@ -118,7 +116,6 @@ async function processFile(
   // Fall back to title if shortTitle doesn't exist.
   const slug: string = slugger.slug(decode(stringToSlugify))
 
-  // Get the basename, depending on whether it's a file or dir.
   let basename: string
   if (isDirectory) {
     // Where: content location = content/foobar/index.md
@@ -133,12 +130,10 @@ async function processFile(
   // If slug and basename already match, all set here. Return early.
   if (slug === basename) return null
 
-  // Build the new path based on file type.
   const newPath = isDirectory
     ? path.join(path.dirname(path.dirname(file)), slug, 'index.md')
     : path.join(path.dirname(file), `${slug}.md`)
 
-  // Get relative paths and adjust for directories.
   const getContentPath = (filePath: string): string => {
     const relativePath = path.relative(process.cwd(), filePath)
     return isDirectory ? path.dirname(relativePath) : relativePath
@@ -187,26 +182,21 @@ function sortFiles(filesArray: string[]): string[] {
   // 2. Deepest subdirectory path
   // 3. Shallowest subdirectory path (up to category level, e.g., content/product/category)
   return filesArray.toSorted((a, b) => {
-    // If A is a file and B is a directory, A comes first (negative)
     if (!isDirectoryCheck(a) && isDirectoryCheck(b)) {
       return -1
     }
-    // If A is a directory and B is a file, B comes first (positive)
     if (isDirectoryCheck(a) && !isDirectoryCheck(b)) {
       return 1
     }
-    // If A and B are both files, neutral
     if (!isDirectoryCheck(a) && !isDirectoryCheck(b)) {
       return 0
     }
-    // If both are directories, sort by depth (deepest first)
     if (isDirectoryCheck(a) && isDirectoryCheck(b)) {
       const aDepth = a.split(path.sep).length
       const bDepth = b.split(path.sep).length
       return bDepth - aDepth // Deeper paths first
     }
 
-    // This should never be reached, but return 0 for safety
     return 0
   })
 }
@@ -246,20 +236,16 @@ function determineProcessStatus(
   isDirectory: boolean,
   scriptOptions: ScriptOptions,
 ): boolean {
-  // Assess the conditions in this order:
-  // If it's a directory AND we're excluding dirs, do not process it no matter what.
+  // A directory is never processed when dirs are excluded, whatever else is set.
   if (isDirectory && scriptOptions.excludeDirs) {
     return false
   }
-  // If the force option is passed, process it no matter what.
   if (scriptOptions.force) {
     return true
   }
-  // If the page has the override set, do not process it.
   if (data.allowTitleToDifferFromFilename) {
     return false
   }
-  // In all other cases, process it.
   return true
 }
 

From 3c379b6305c6ec5a5105612c9527420ca68359b0 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:16:40 +0000
Subject: [PATCH 03/16] Trim excessive comments in src/graphql and src/fixtures
 (#63275)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/fixtures/playwright.config.ts             | 14 ------
 src/fixtures/tests/api-article-body.ts        | 15 ------
 .../tests/categories-and-subcategory.ts       |  4 +-
 src/fixtures/tests/playwright-a11y.spec.ts    |  4 +-
 .../tests/playwright-rendering.spec.ts        | 50 ++-----------------
 src/graphql/components/GraphqlItem.tsx        |  2 +-
 src/graphql/components/GraphqlPage.tsx        |  5 +-
 src/graphql/lib/validator.ts                  | 14 ------
 src/graphql/scripts/build-changelog.ts        | 21 +-------
 src/graphql/scripts/sync.ts                   |  8 +--
 src/graphql/scripts/utils/process-previews.ts |  1 -
 src/graphql/scripts/utils/process-schemas.ts  | 34 +++++--------
 12 files changed, 29 insertions(+), 143 deletions(-)

diff --git a/src/fixtures/playwright.config.ts b/src/fixtures/playwright.config.ts
index 9ba48a14ccaf..7d4e382171aa 100644
--- a/src/fixtures/playwright.config.ts
+++ b/src/fixtures/playwright.config.ts
@@ -1,11 +1,5 @@
 import { defineConfig } from '@playwright/test'
 
-/**
- * Read environment variables from file.
- * https://github.com/motdotla/dotenv
- */
-// require('dotenv').config();
-
 const CI = Boolean(JSON.parse(process.env.CI || 'false'))
 
 const PLAYWRIGHT_START_SERVER_COMMAND =
@@ -36,7 +30,6 @@ const EXPECT_TIMEOUT = process.env.PLAYWRIGHT_EXPECT_TIMEOUT
  */
 export default defineConfig({
   testDir: './tests',
-  /* Maximum time one test can run for. */
   timeout: TIMEOUT,
   expect: {
     /**
@@ -45,13 +38,9 @@ export default defineConfig({
      */
     timeout: EXPECT_TIMEOUT,
   },
-  /* Run tests in files in parallel */
   fullyParallel: true,
-  /* Fail the build on CI if you accidentally left test.only in the source code. */
   forbidOnly: !!process.env.CI,
-  /* Retry on CI only */
   retries: RETRIES,
-  /* Opt out of parallel tests on CI. */
   workers: process.env.PLAYWRIGHT_WORKERS
     ? JSON.parse(process.env.PLAYWRIGHT_WORKERS)
     : CI
@@ -63,14 +52,12 @@ export default defineConfig({
   use: {
     /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). */
     actionTimeout: 0,
-    /* Base URL to use in actions like `await page.goto('/')`. */
     baseURL: 'http://localhost:4000',
 
     /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
     trace: 'on-first-retry',
   },
 
-  /* Configure projects for major browsers */
   projects: [
     // {
     //   name: 'chromium',
@@ -125,7 +112,6 @@ export default defineConfig({
   /* Folder for test artifacts such as screenshots, videos, traces, etc. */
   // outputDir: 'test-results/',
 
-  /* Run your local dev server before starting the tests */
   webServer: {
     command: PLAYWRIGHT_START_SERVER_COMMAND,
     port: 4000,
diff --git a/src/fixtures/tests/api-article-body.ts b/src/fixtures/tests/api-article-body.ts
index 05006793549c..fb4d3de6d23a 100644
--- a/src/fixtures/tests/api-article-body.ts
+++ b/src/fixtures/tests/api-article-body.ts
@@ -55,9 +55,7 @@ describe('article body api', () => {
     const res = await get(makeURL('/en/get-started/start-your-journey/api-article-body-test-page'))
 
     expect(res.statusCode).toBe(200)
-    // Should not contain frontmatter
     expect(res.body).not.toMatch(/^---/)
-    // Should have at least one heading
     expect(res.body).toMatch(/^#{1,6}\s+\w+/m)
   })
 
@@ -80,21 +78,17 @@ describe('article body api', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Should contain all tool-specific content variants
     expect(res.body).toContain('<div class="ghd-tool webui">')
     expect(res.body).toContain('<div class="ghd-tool cli">')
     expect(res.body).toContain('<div class="ghd-tool desktop">')
 
-    // Should contain the actual content from each tool
     expect(res.body).toContain('This is webui content')
     expect(res.body).toContain('This is cli content')
     expect(res.body).toContain('This is desktop content')
 
-    // Should contain tool-specific sections
     expect(res.body).toContain('Webui section specific content')
     expect(res.body).toContain('Desktop section specific content')
 
-    // Verify multiple instances of the same tool are preserved
     const webuiMatches = res.body.match(/<div class="ghd-tool webui">/g)
     const desktopMatches = res.body.match(/<div class="ghd-tool desktop">/g)
     expect(webuiMatches).toBeDefined()
@@ -108,11 +102,9 @@ describe('article body api', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Should contain both webui and codespaces tool content
     expect(res.body).toContain('<div class="ghd-tool webui">')
     expect(res.body).toContain('<div class="ghd-tool codespaces">')
 
-    // Should contain the actual content from both tools
     expect(res.body).toContain('Under your repository name, click **Pull requests**')
     expect(res.body).toContain('Open the pull request in your codespace')
     expect(res.body).toContain(
@@ -122,7 +114,6 @@ describe('article body api', () => {
       'After reviewing the files, you can submit your review directly from Codespaces',
     )
 
-    // Verify both tools appear in multiple sections
     const webuiMatches = res.body.match(/<div class="ghd-tool webui">/g)
     const codespacesMatches = res.body.match(/<div class="ghd-tool codespaces">/g)
     expect(webuiMatches).toBeDefined()
@@ -139,7 +130,6 @@ describe('article body api', () => {
       ),
     )
 
-    // Skip test if page doesn't exist in fixture environment
     if (res.statusCode === 404) {
       console.log('Production page not available in fixture environment, skipping test')
       return
@@ -147,11 +137,9 @@ describe('article body api', () => {
 
     expect(res.statusCode).toBe(200)
 
-    // Verify the fix is working - codespaces content should now be present
     const hasCodespacesContent = res.body.includes('<div class="ghd-tool codespaces">')
     expect(hasCodespacesContent).toBe(true)
 
-    // Also verify that webui content is still present
     expect(res.body).toContain('<div class="ghd-tool webui">')
   })
 
@@ -164,7 +152,6 @@ describe('article body api', () => {
       ),
     )
 
-    // Skip test if page doesn't exist in fixture environment
     if (res.statusCode === 404) {
       console.log(
         'Production page not available in fixture environment, skipping issue verification test',
@@ -179,11 +166,9 @@ describe('article body api', () => {
     expect(res.body).toContain('<div class="ghd-tool webui">')
     expect(res.body).toContain('<div class="ghd-tool codespaces">')
 
-    // Verify specific codespaces content that was missing before the fix
     expect(res.body).toContain('GitHub Codespaces')
     expect(res.body).toContain('Open the pull request in a codespace')
 
-    // Ensure both tools are rendered with their respective content
     const webuiMatches = res.body.match(/<div class="ghd-tool webui">/g)
     const codespacesMatches = res.body.match(/<div class="ghd-tool codespaces">/g)
 
diff --git a/src/fixtures/tests/categories-and-subcategory.ts b/src/fixtures/tests/categories-and-subcategory.ts
index fcbf6375987d..24aa47af6056 100644
--- a/src/fixtures/tests/categories-and-subcategory.ts
+++ b/src/fixtures/tests/categories-and-subcategory.ts
@@ -17,7 +17,7 @@ describe('subcategories', () => {
     expect(
       hrefs.every((href: string) => href.startsWith('/en/get-started/start-your-journey/')),
     ).toBeTruthy()
-    // The all resolve to a 200 OK without redirects
+    // They all resolve to a 200 OK without redirects
     const responses = await Promise.all(hrefs.map((href: string) => head(href)))
     expect(responses.every((r: { statusCode: number }) => r.statusCode === 200)).toBeTruthy()
   })
@@ -53,7 +53,7 @@ describe('categories', () => {
     // They all have the same prefix
     const hrefs = links.map((i: number, el: Element) => $(el).attr('href')).get()
     expect(hrefs.every((href: string) => href.startsWith('/en/actions/category/'))).toBeTruthy()
-    // The all resolve to a 200 OK without redirects
+    // They all resolve to a 200 OK without redirects
     const responses = await Promise.all(hrefs.map((href: string) => head(href)))
     expect(responses.every((r: { statusCode: number }) => r.statusCode === 200)).toBeTruthy()
   })
diff --git a/src/fixtures/tests/playwright-a11y.spec.ts b/src/fixtures/tests/playwright-a11y.spec.ts
index 0eacad14ed50..e3e24039c38d 100644
--- a/src/fixtures/tests/playwright-a11y.spec.ts
+++ b/src/fixtures/tests/playwright-a11y.spec.ts
@@ -54,8 +54,8 @@ for (const pageName of Object.keys(pages)) {
 // otherwise never be scanned.
 test.describe('search filters (narrow viewport)', () => {
   // Without a local Elasticsearch the middleware proxies to production, so there are no
-  // aggregations, the disclosure never renders, and this would time out rather than skip
-  // — matching the guard every search test in playwright-rendering.spec.ts uses.
+  // aggregations, the disclosure never renders, and this would time out rather than
+  // skip. Matches the guard every search test in playwright-rendering.spec.ts uses.
   test.skip(!SEARCH_TESTS, 'No local Elasticsearch, no tests involving search')
 
   test('expanded filter disclosure passes axe', async ({ page }) => {
diff --git a/src/fixtures/tests/playwright-rendering.spec.ts b/src/fixtures/tests/playwright-rendering.spec.ts
index 461b8e3643a6..c5e18a7880b8 100644
--- a/src/fixtures/tests/playwright-rendering.spec.ts
+++ b/src/fixtures/tests/playwright-rendering.spec.ts
@@ -145,12 +145,9 @@ test('do a search from home page and click on "Foo" page', async ({ page }) => {
   await page.goto('/')
   await turnOffExperimentsInPage(page)
 
-  // Use the search overlay
   await page.locator('[data-testid="search"]:visible').click()
   await page.getByTestId('overlay-search-input').fill('serve playwright')
-  // Wait for search results to load
   await page.waitForTimeout(1000)
-  // Click "View more results" to get to the search page
   await page.getByText('View more results').click()
 
   await expect(page).toHaveURL(
@@ -202,9 +199,7 @@ test('open search, and select a general search article', async ({ page }) => {
   // Let new suggestions load
   const searchOverlay = page.getByTestId('general-autocomplete-suggestions')
   await expect(searchOverlay.getByText('For Playwright')).toBeVisible()
-  // Navigate to general search item, "For Playwright"
   await page.keyboard.press('ArrowDown')
-  // Select the general search item, "For Playwright"
   await page.keyboard.press('Enter')
 
   // We should now be on the page for "For Playwright"
@@ -241,9 +236,7 @@ test('open search, and get auto-complete results', async ({ page }) => {
   await expect(searchInput).toBeVisible()
   await expect(searchInput).toBeEnabled()
 
-  // Type the text "rest" into the search input
   await searchInput.fill('rest')
-  // For for 1 second for the suggestions to load
   await page.waitForTimeout(1000)
 
   // Ask AI suggestions
@@ -267,12 +260,9 @@ test('search from enterprise-cloud and filter by top-level Fooing', async ({ pag
   await page.goto('/enterprise-cloud@latest')
   await turnOffExperimentsInPage(page)
 
-  // Use the search overlay
   await page.locator('[data-testid="search"]:visible').click()
   await page.getByTestId('overlay-search-input').fill('fixture')
-  // Wait for search results to load
   await page.waitForTimeout(1000)
-  // Click "View more results" to get to the search page
   await page.getByText('View more results').click()
 
   // Now we're on the search results page, apply the filter
@@ -309,7 +299,7 @@ test.describe('platform picker', () => {
   })
 
   test('minitoc matches picker', async ({ page }) => {
-    // default platform set to windows in fixture fronmatter
+    // The fixture frontmatter defaults the platform to Windows.
     await page.goto('/get-started/liquid/platform-specific')
     await turnOffExperimentsInPage(page)
     await expect(
@@ -450,12 +440,10 @@ test('navigate with side bar into article inside a subcategory inside a category
 })
 
 test('sidebar custom link functionality works', async ({ page }) => {
-  // Test that sidebar functionality is not broken by custom links feature
   await page.goto('/get-started')
 
   await expect(page).toHaveTitle(/Getting started with HubGit/)
 
-  // Verify that regular sidebar navigation still works by clicking on known sections
   await page.getByTestId('product-sidebar').getByText('Start your journey').click()
   await page.getByTestId('product-sidebar').getByText('Hello World').click()
   await expect(page).toHaveURL(/\/en\/get-started\/start-your-journey\/hello-world/)
@@ -550,7 +538,6 @@ test.describe('hover cards', () => {
       ),
     ).toBeVisible()
 
-    // Press Escape to close it
     await page.keyboard.press('Escape')
     await expect(
       page.getByText(
@@ -574,7 +561,6 @@ test.describe('hover cards', () => {
       ),
     ).toBeVisible()
 
-    // click the Esc key to close the hovercard
     await page.keyboard.press('Escape')
     await expect(
       page.getByText(
@@ -603,7 +589,7 @@ test.describe('test nav at different viewports', () => {
     await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
 
     // breadcrumbs show up in one of the pages that use the AutomatedPage
-    // component (e.g. graphql, audit log, etc.) -- we test the webhooks
+    // component (e.g. graphql, audit log). This one uses the webhooks
     // reference page here
     await page.goto('/webhooks/webhook-events-and-payloads')
     await expect(page.getByTestId('breadcrumbs-bar')).toBeVisible()
@@ -627,7 +613,7 @@ test.describe('test nav at different viewports', () => {
       height: 700,
     })
 
-    // Opening the mobile nav must still render the doc-tree drawer -- before the
+    // Opening the mobile nav must still render the doc-tree drawer. Before the
     // fix, `collapsed` short-circuited the sidebar to null while the open state
     // hid the content column, leaving a blank area with no drawer.
     await page.getByTestId('sidebar-mobile-toggle').click()
@@ -651,7 +637,7 @@ test.describe('test nav at different viewports', () => {
     const nav = page.locator('[data-container="nav"]')
     await expect(nav).toHaveAttribute('data-mobile-open', 'true')
 
-    // Resize up to the desktop breakpoint -- the inline nav should close and the
+    // Resize up to the desktop breakpoint. The inline nav should close and the
     // fixed desktop rail (326px) should take over rather than the full-width
     // mobile markup persisting over the page.
     await page.setViewportSize({
@@ -669,16 +655,13 @@ test.describe('test nav at different viewports', () => {
     })
     await page.goto('/get-started/foo/bar')
 
-    // version picker should be visible
     await page.getByTestId('version-picker').getByRole('button').click()
     expect((await page.getByRole('menuitemradio').all()).length).toBeGreaterThan(0)
     await expect(page.getByRole('menuitemradio', { name: 'Enterprise Cloud' })).toBeVisible()
 
-    // language picker is visible
     await page.getByRole('button', { name: 'Select language: current language is English' }).click()
     await expect(page.getByRole('menuitemradio', { name: 'English' })).toBeVisible()
 
-    // header sign up button is visible
     await expect(page.getByTestId('header-signup')).toBeVisible()
   })
 
@@ -707,19 +690,15 @@ test.describe('test nav at different viewports', () => {
     })
     await page.goto('/get-started/foo/bar')
 
-    // version picker is visible
     await page.getByTestId('version-picker').getByRole('button').click()
     expect((await page.getByRole('menuitemradio').all()).length).toBeGreaterThan(0)
     await expect(page.getByRole('menuitemradio', { name: 'Enterprise Cloud' })).toBeVisible()
 
-    // language picker is in mobile menu
     await page.getByTestId('mobile-menu').click()
     await expect(page.getByRole('menuitemradio', { name: 'English' })).toBeVisible()
 
-    // sign up button is in mobile menu
     await expect(page.getByTestId('mobile-signup')).toBeVisible()
 
-    // hamburger button for sidebar overlay is visible
     await expect(page.getByTestId('sidebar-mobile-toggle')).toBeVisible()
     await page.getByTestId('sidebar-mobile-toggle').click()
     await expect(page.getByTestId('sidebar')).toBeVisible()
@@ -732,23 +711,17 @@ test.describe('test nav at different viewports', () => {
     })
     await page.goto('/get-started/foo/bar')
 
-    // header sign-up button is not visible
     await expect(page.getByTestId('header-signup')).not.toBeVisible()
 
-    // language picker is not visible
     await expect(page.getByTestId('language-picker')).not.toBeVisible()
 
-    // version picker is visible
     await expect(page.getByTestId('version-picker').getByRole('button')).toBeVisible()
 
-    // language picker is in mobile menu
     await page.getByTestId('mobile-menu').click()
     await expect(page.getByRole('menuitemradio', { name: 'English' })).toBeVisible()
 
-    // sign up button is in mobile menu
     await expect(page.getByTestId('mobile-signup')).toBeVisible()
 
-    // hamburger button for sidebar overlay is visible
     await expect(page.getByTestId('sidebar-mobile-toggle')).toBeVisible()
     await page.getByTestId('sidebar-mobile-toggle').click()
     await expect(page.getByTestId('sidebar')).toBeVisible()
@@ -762,27 +735,20 @@ test.describe('test nav at different viewports', () => {
     await page.goto('/get-started/foo/bar')
     await turnOffExperimentsInPage(page)
 
-    // header sign-up button is not visible
     await expect(page.getByTestId('header-signup')).not.toBeVisible()
 
-    // language picker is not visible
     await expect(page.getByTestId('language-picker')).not.toBeVisible()
 
-    // version picker is not visible
     await expect(page.getByTestId('version-picker').getByRole('button')).not.toBeVisible()
 
-    // version picker is in mobile menu
     await expect(page.getByTestId('version-picker')).not.toBeVisible()
     await page.getByTestId('mobile-menu').click()
     await expect(page.getByTestId('open-mobile-menu').getByTestId('version-picker')).toBeVisible()
 
-    // language picker is in mobile menu
     await expect(page.getByTestId('open-mobile-menu').getByTestId('language-picker')).toBeVisible()
 
-    // sign up button is in mobile menu
     await expect(page.getByTestId('mobile-signup')).toBeVisible()
 
-    // hamburger button for sidebar overlay is visible
     await expect(page.getByTestId('sidebar-mobile-toggle')).toBeVisible()
     await page.getByTestId('sidebar-mobile-toggle').click()
     await expect(page.getByTestId('sidebar')).toBeVisible()
@@ -798,12 +764,9 @@ test.describe('test nav at different viewports', () => {
     await page.goto('/get-started/foo/bar')
     await turnOffExperimentsInPage(page)
 
-    // Use the search overlay
     await page.locator('[data-testid="mobile-search-button"]:visible').click()
     await page.getByTestId('overlay-search-input').fill('serve playwright')
-    // Wait for search results to load
     await page.waitForTimeout(1000)
-    // Click "View more results" to get to the search page
     await page.getByText('View more results').click()
 
     await expect(page).toHaveURL(
@@ -822,12 +785,9 @@ test.describe('test nav at different viewports', () => {
     await page.goto('/get-started/foo/bar')
     await turnOffExperimentsInPage(page)
 
-    // Use the search overlay
     await page.locator('[data-testid="mobile-search-button"]:visible').click()
     await page.getByTestId('overlay-search-input').fill('serve playwright')
-    // Wait for search results to load
     await page.waitForTimeout(1000)
-    // Click "View more results" to get to the search page
     await page.getByText('View more results').click()
 
     await expect(page).toHaveURL(
@@ -841,7 +801,7 @@ test.describe('secondary-bar breadcrumb scroller', () => {
   // The secondary bar (and its breadcrumb scroller) only renders at wide
   // viewports, and the fixture trail is short enough to fit there, so we cap the
   // scroller width to force a deterministic overflow independent of title
-  // lengths — then exercise the chevrons.
+  // lengths, then exercise the chevrons.
   test('chevrons scroll one crumb at a time instead of jumping to the ends', async ({ page }) => {
     // Smooth-scroll settle waits across several chevron clicks add up past the
     // default 5s cap.
diff --git a/src/graphql/components/GraphqlItem.tsx b/src/graphql/components/GraphqlItem.tsx
index c15af9d85014..fe05f8f0b74d 100644
--- a/src/graphql/components/GraphqlItem.tsx
+++ b/src/graphql/components/GraphqlItem.tsx
@@ -18,7 +18,7 @@ type Props = {
   kind?: SchemaKindKey
 }
 
-// Clamp a numeric heading level to the valid HTML range (2–6). Used to
+// Clamp a numeric heading level to the valid HTML range (2-6). Used to
 // build heading tag names like `h2`/`h3` from a numeric `headingLevel`
 // prop without producing invalid tags if a caller passes something odd.
 function headingTag(level: number): keyof JSX.IntrinsicElements {
diff --git a/src/graphql/components/GraphqlPage.tsx b/src/graphql/components/GraphqlPage.tsx
index f6201f6d5488..6af3dc924792 100644
--- a/src/graphql/components/GraphqlPage.tsx
+++ b/src/graphql/components/GraphqlPage.tsx
@@ -30,9 +30,8 @@ type Props = {
 export const GraphqlPage = ({ schema, pageName, objects }: Props) => {
   const graphqlItems: JSX.Element[] = [] // In the case of the H2s for Queries
 
-  // The queries page has two heading sections (connections and fields)
-  // So we need to add the heading component and the children under it
-  // for each section.
+  // The queries page has two heading sections (connections and fields), so add
+  // the heading component and its children once per section.
   if (pageName === 'queries') {
     graphqlItems.push(
       ...(schema as QueryT[]).map((item) => <Query item={item} key={item.id + item.name} />),
diff --git a/src/graphql/lib/validator.ts b/src/graphql/lib/validator.ts
index be7e085db81c..89283c83e5a5 100644
--- a/src/graphql/lib/validator.ts
+++ b/src/graphql/lib/validator.ts
@@ -1,7 +1,6 @@
 // the tests in tests/graphql.ts use this schema to ensure the integrity
 // of the data in src/graphql/data/*.json
 
-// JSON Schema type definitions for AJV validation
 interface JSONSchema {
   type?: string
   required?: string[]
@@ -16,7 +15,6 @@ interface ValidatorSchema extends JSONSchema {
   properties: Record<string, JSONSchema>
 }
 
-// PREVIEWS
 export const previewsValidator: ValidatorSchema = {
   type: 'object',
   required: [
@@ -53,7 +51,6 @@ export const previewsValidator: ValidatorSchema = {
   },
 }
 
-// UPCOMING CHANGES
 export const upcomingChangesValidator: ValidatorSchema = {
   type: 'object',
   required: ['location', 'description', 'reason', 'date', 'criticality', 'owner'],
@@ -82,7 +79,6 @@ export const upcomingChangesValidator: ValidatorSchema = {
   },
 }
 
-// SCHEMAS
 // many GraphQL schema members have these core properties
 const coreProps: JSONSchema = {
   properties: {
@@ -133,13 +129,11 @@ delete corePropsNoType.properties!.type
 const corePropsNoDescription = dup(coreProps)
 delete corePropsNoDescription.properties!.description
 
-// QUERIES
 const queries = dup(corePropsPlusArgs) as ValidatorSchema
 
 queries.type = 'object'
 queries.required = ['name', 'type', 'id', 'href', 'description']
 
-// MUTATIONS
 const mutations = dup(corePropsNoType) as ValidatorSchema
 
 mutations.type = 'object'
@@ -161,7 +155,6 @@ mutations.properties.returnFields = {
   },
 }
 
-// OBJECTS
 const objects = dup(corePropsNoType) as ValidatorSchema
 
 objects.type = 'object'
@@ -194,7 +187,6 @@ objects.properties.implements = {
   },
 }
 
-// INTERFACES
 const interfaces = dup(corePropsNoType) as ValidatorSchema
 
 interfaces.type = 'object'
@@ -208,7 +200,6 @@ interfaces.properties.fields = {
   },
 }
 
-// ENUMS
 const enums = dup(corePropsNoType) as ValidatorSchema
 
 enums.type = 'object'
@@ -230,7 +221,6 @@ enums.properties.values = {
   },
 }
 
-// UNIONS
 const unions = dup(corePropsNoType) as ValidatorSchema
 
 unions.type = 'object'
@@ -255,7 +245,6 @@ unions.properties.possibleTypes = {
   },
 }
 
-// INPUT OBJECTS
 const inputObjects = dup(corePropsNoType) as ValidatorSchema
 
 inputObjects.type = 'object'
@@ -269,18 +258,15 @@ inputObjects.properties.inputFields = {
   },
 }
 
-// SCALARS
 const scalars = dup(corePropsNoType) as ValidatorSchema
 
 scalars.type = 'object'
 scalars.required = ['name', 'id', 'href', 'description']
 
-// Deep clone utility function with proper typing
 function dup<T>(obj: T): T {
   return JSON.parse(JSON.stringify(obj))
 }
 
-// Schema validator collection with proper typing
 interface SchemaValidators {
   queries: ValidatorSchema
   mutations: ValidatorSchema
diff --git a/src/graphql/scripts/build-changelog.ts b/src/graphql/scripts/build-changelog.ts
index 11acb66f209b..0b645a4e7f52 100644
--- a/src/graphql/scripts/build-changelog.ts
+++ b/src/graphql/scripts/build-changelog.ts
@@ -65,16 +65,12 @@ let lastIgnoredChanges: Change[] = []
  * structure written to `targetPath`. (`changelogEntry` and that file are modified in place.)
  */
 export function prependDatedEntry(changelogEntry: ChangelogEntry, targetPath: string): void {
-  // Build a `yyyy-mm-dd`-formatted date string
-  // and tag the changelog entry with it
   const todayString = new Date().toISOString().slice(0, 10)
   changelogEntry.date = todayString
 
   const previousChangelogString = fs.readFileSync(targetPath, 'utf8')
   const previousChangelog = JSON.parse(previousChangelogString) as ChangelogEntry[]
-  // add a new entry to the changelog data
   previousChangelog.unshift(changelogEntry)
-  // rewrite the updated changelog
   fs.writeFileSync(targetPath, JSON.stringify(previousChangelog, null, 2))
 
   // Ensure a content page exists for this entry's year
@@ -108,7 +104,6 @@ export function ensureYearPage(
   ].join('\n')
   fs.writeFileSync(yearPagePath, yearPage)
 
-  // Prepend the new year to children in index.md
   const indexPath = nodePath.join(contentDir, 'index.md')
   const indexContent = fs.readFileSync(indexPath, 'utf8')
   const updated = indexContent.replace(/^(children:\n)/m, `$1  - /${year}\n`)
@@ -128,11 +123,9 @@ export async function createChangelogEntry(
   oldUpcomingChanges: UpcomingChange[],
   newUpcomingChanges: UpcomingChange[],
 ): Promise<ChangelogEntry | null> {
-  // Create schema objects out of the strings
   const oldSchema = await loadSchema(oldSchemaString, { loaders: [] })
   const newSchema = await loadSchema(newSchemaString, { loaders: [] })
 
-  // Generate changes between the two schemas
   const changes = await diff(oldSchema, newSchema)
   const changesToReport: Change[] = []
   const ignoredChanges: Change[] = []
@@ -140,12 +133,10 @@ export async function createChangelogEntry(
     if (CHANGES_TO_REPORT.includes(change.type)) {
       changesToReport.push(change)
     } else {
-      // Track ignored changes for visibility
       ignoredChanges.push(change)
     }
   }
 
-  // Log warnings for ignored change types to provide visibility
   if (ignoredChanges.length > 0) {
     const ignoredTypes = [...new Set(ignoredChanges.map((change) => change.type))]
     console.warn(
@@ -160,7 +151,6 @@ export async function createChangelogEntry(
     )
   }
 
-  // Store ignored changes for potential workflow outputs
   lastIgnoredChanges = ignoredChanges
 
   const { schemaChangesToReport, previewChangesToReport } = segmentPreviewChanges(
@@ -180,7 +170,6 @@ export async function createChangelogEntry(
     })
   })
 
-  // If there were any changes, create a changelog entry
   if (
     schemaChangesToReport.length > 0 ||
     Object.keys(previewChangesToReport).length > 0 ||
@@ -365,19 +354,13 @@ const CHANGES_TO_REPORT = [
   ChangeType.DirectiveUsageFieldDefinitionRemoved,
 ]
 
-// CHANGES_TO_IGNORE list removed - now we only process changes explicitly listed
-// in CHANGES_TO_REPORT and silently ignore all others for future compatibility
+// Anything not in CHANGES_TO_REPORT is logged as ignored rather than reported,
+// so a new change type added upstream cannot break this script.
 
-/**
- * Get the ignored change types from the last changelog entry creation
- */
 export function getLastIgnoredChanges(): Change[] {
   return lastIgnoredChanges
 }
 
-/**
- * Get summary of ignored change types for workflow outputs
- */
 export function getIgnoredChangesSummary(): IgnoredChangesSummary | null {
   const ignored = getLastIgnoredChanges()
   if (ignored.length === 0) return null
diff --git a/src/graphql/scripts/sync.ts b/src/graphql/scripts/sync.ts
index 15fe3eb165e3..6293964ded4f 100755
--- a/src/graphql/scripts/sync.ts
+++ b/src/graphql/scripts/sync.ts
@@ -18,7 +18,6 @@ import {
   getIgnoredChangesSummary,
 } from './build-changelog'
 
-// Type definitions
 interface GitHubRepoOptions {
   owner: string
   repo: string
@@ -79,7 +78,7 @@ const allIgnoredChanges: IgnoredChange[] = []
 
 async function main() {
   for (const version of versionsToBuild) {
-    // Get the relevant GraphQL name  for the current version
+    // Get the relevant GraphQL name for the current version.
     // For example, free-pro-team@latest corresponds to dotcom,
     // enterprise-server@2.22 corresponds to ghes-2.22.
     const graphqlVersion = allVersions[version].openApiVersionName
@@ -198,7 +197,7 @@ async function main() {
   // children and disappearance redirects, based on the presence collected above.
   await syncCategoryContentFiles(categoryPresence)
 
-  // Ensure the YAML linter runs before checkinging in files
+  // Run the YAML linter before anything is checked in.
   execSync('npx prettier -w "**/*.{yml,yaml}"')
 
   // Output ignored changes for GitHub Actions
@@ -212,7 +211,6 @@ async function main() {
       '::notice title=GraphQL Ignored Changes::Found ignored change types that may need review',
     )
 
-    // Write outputs to GitHub Actions output file
     if (process.env.GITHUB_OUTPUT) {
       appendFileSync(
         process.env.GITHUB_OUTPUT,
@@ -237,7 +235,6 @@ async function getRemoteRawContent(filepath: string, graphqlVersion: string) {
   let took = new Date().getTime() - t0
   console.log(`Got ref (${options.ref}) for '${graphqlVersion}'. Took ${formatTime(took)}`)
 
-  // add the filepath to the options so we can get the contents of the file
   options.path = `config/${path.basename(filepath)}`
 
   t0 = new Date().getTime()
@@ -275,7 +272,6 @@ async function getBranchAsRef(
   // the first time this runs, it uses the branch found for the version above
   if (!branch) branch = branches[versionType]
 
-  // set the branch as the ref
   const ref = `heads/${branch}`
 
   // check whether the branch can be found in github/github
diff --git a/src/graphql/scripts/utils/process-previews.ts b/src/graphql/scripts/utils/process-previews.ts
index 3845fe1061a4..4a9197faa42f 100644
--- a/src/graphql/scripts/utils/process-previews.ts
+++ b/src/graphql/scripts/utils/process-previews.ts
@@ -37,7 +37,6 @@ export default function processPreviews(previews: RawPreview[]): ProcessedPrevie
     // remove unnecessary leading colon
     const toggled_by = raw.toggled_by.replace(':', '')
 
-    // add convenience properties
     const accept_header = `application/vnd.github.${toggled_by}+json`
 
     slugger.reset()
diff --git a/src/graphql/scripts/utils/process-schemas.ts b/src/graphql/scripts/utils/process-schemas.ts
index 9004c9c81234..9abfd2995ee2 100755
--- a/src/graphql/scripts/utils/process-schemas.ts
+++ b/src/graphql/scripts/utils/process-schemas.ts
@@ -235,13 +235,12 @@ const externalScalars: ScalarInfo[] = await Promise.all(
   }),
 )
 
-// select and format all the data from the schema that we need for the docs
-// used in the build step
 // Shape of the per-version `category-map.json` used both at runtime by the
 // redirect middleware and (here) at build time as a fallback source of
 // categories when a schema lacks `@docsCategory` directives.
 type CategoryMapFallback = Partial<Record<string, Record<string, string>>>
 
+// Selects and formats the schema data the docs need. Runs in the build step.
 export default async function processSchemas(
   idl: Buffer | string,
   previewsPerVersion: PreviewInfo[],
@@ -521,17 +520,18 @@ export default async function processSchemas(
     }
   }
 
-  // Normalize unknown categories (e.g. `:checks`, `:search`, `:packages`,
-  // `:security_advisories`) to `other`. The upstream gh/gh allowlist permits
-  // many categories that docs-internal hasn't yet built per-category landing
-  // pages for; without this fallback those types would be silently dropped
-  // by `writeCategoryFiles` (which only emits files for slugs in CATEGORIES)
-  // and their redirects would 404. Once a page exists for a category, add it
-  // to CATEGORIES in src/graphql/lib/categories.ts and types will move out
-  // of `other` on the next sync.
-  // Resolver used to populate the top-level `.category` field on every
-  // processed item. The bucketer reads `.category` to split the schema into
-  // per-category files and to rewrite cross-reference hrefs.
+  // Populates the top-level `.category` field on every processed item. The
+  // bucketer reads `.category` to split the schema into per-category files and
+  // to rewrite cross-reference hrefs.
+  //
+  // Unknown categories (e.g. `:checks`, `:search`, `:packages`,
+  // `:security_advisories`) normalize to `other`. The upstream gh/gh allowlist
+  // permits many categories that docs-internal has not built per-category
+  // landing pages for; without this fallback those types would be silently
+  // dropped by `writeCategoryFiles` (which only emits files for slugs in
+  // CATEGORIES) and their redirects would 404. Once a page exists for a
+  // category, add it to CATEGORIES in src/graphql/lib/categories.ts and types
+  // will move out of `other` on the next sync.
   const resolveCategory = (typeId: string): string => {
     const cat = typeCategoryMap.get(typeId) ?? fallbackTypeMap[typeId] ?? OTHER_CATEGORY
     return isValidCategory(cat) ? cat : OTHER_CATEGORY
@@ -556,7 +556,6 @@ export default async function processSchemas(
 
   await Promise.all(
     schemaAST.definitions.map(async (def: DefinitionNode) => {
-      // QUERIES
       if (def.kind === 'ObjectTypeDefinition' && def.name.value === 'Query') {
         await Promise.all(
           (def.fields || []).map(async (field: FieldDefinitionNode) => {
@@ -627,7 +626,6 @@ export default async function processSchemas(
         return
       }
 
-      // MUTATIONS
       if (def.kind === 'ObjectTypeDefinition' && def.name.value === 'Mutation') {
         await Promise.all(
           (def.fields || []).map(async (field: FieldDefinitionNode) => {
@@ -732,7 +730,6 @@ export default async function processSchemas(
         return
       }
 
-      // OBJECTS
       if (def.kind === 'ObjectTypeDefinition') {
         // objects ending with 'Payload' are only used to derive mutation values
         // they are not included in the objects docs
@@ -817,7 +814,6 @@ export default async function processSchemas(
         return
       }
 
-      // INTERFACES
       if (def.kind === 'InterfaceTypeDefinition') {
         const graphqlInterface: Partial<GraphQLInterfaceInfo> = {}
         const interfaceFields: FieldInfo[] = []
@@ -882,7 +878,6 @@ export default async function processSchemas(
         return
       }
 
-      // ENUMS
       if (def.kind === 'EnumTypeDefinition') {
         const graphqlEnum: Partial<EnumInfo> = {}
         const enumValues: EnumValueInfo[] = []
@@ -922,7 +917,6 @@ export default async function processSchemas(
         return
       }
 
-      // UNIONS
       if (def.kind === 'UnionTypeDefinition') {
         const union: Partial<UnionInfo> = {}
         const possibleTypes: PossibleTypeInfo[] = []
@@ -1027,7 +1021,6 @@ export default async function processSchemas(
         return
       }
 
-      // SCALARS
       if (def.kind === 'ScalarTypeDefinition') {
         const scalar: ScalarInfo = {
           name: def.name.value,
@@ -1058,7 +1051,6 @@ export default async function processSchemas(
   // add non-schema scalars and sort all scalars alphabetically
   data.scalars = sortBy(data.scalars.concat(externalScalars), 'name')
 
-  // sort all the types alphabetically
   data.queries = sortBy(data.queries, 'name')
   data.mutations = sortBy(data.mutations, 'name')
   data.objects = sortBy(data.objects, 'name')

From dd5e7bc8df630940d8f6fedf0c97a1968b16b652 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:16:54 +0000
Subject: [PATCH 04/16] Clean up comments in src/links/scripts (#63272)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/links/scripts/action-injections.ts        |  6 +-
 .../scripts/check-github-github-links.ts      |  7 +--
 src/links/scripts/check-links-external.ts     | 58 ++-----------------
 src/links/scripts/check-links-internal.ts     | 44 +++++---------
 src/links/scripts/check-links-pr.ts           | 29 +---------
 src/links/scripts/debug-time-taken.ts         |  4 +-
 src/links/scripts/upload-artifact.ts          |  8 +--
 .../post-pr-comment.ts                        | 10 ++--
 .../validate.ts                               |  2 +-
 9 files changed, 37 insertions(+), 131 deletions(-)

diff --git a/src/links/scripts/action-injections.ts b/src/links/scripts/action-injections.ts
index 928bc6996ddb..9764df2ce79c 100644
--- a/src/links/scripts/action-injections.ts
+++ b/src/links/scripts/action-injections.ts
@@ -1,7 +1,5 @@
-/*
- * Dependency injection for scripts that call .github/actions/ code
- * Replaces action platform specific functionality with local machine functionality
- */
+// Dependency injection for scripts that call .github/actions/ code.
+// Swaps the Actions-platform pieces for local-machine equivalents.
 
 import fs from 'fs'
 import path from 'path'
diff --git a/src/links/scripts/check-github-github-links.ts b/src/links/scripts/check-github-github-links.ts
index dd612a304b20..e610830834c8 100755
--- a/src/links/scripts/check-github-github-links.ts
+++ b/src/links/scripts/check-github-github-links.ts
@@ -51,9 +51,8 @@ main(program.opts(), program.args)
 const retryConfiguration = {
   limit: 3,
 }
-// According to our Datadog metrics, the *average* time for the
-// the 'archive_enterprise_proxy' metric is ~70ms (excluding spikes)
-// which much less than 500ms.
+// Datadog puts the average time for the `archive_enterprise_proxy` metric at
+// around 70ms, excluding spikes, well under the 3s request timeout below.
 const timeoutConfiguration = {
   request: 3000,
 }
@@ -87,7 +86,7 @@ async function main(opts: MainOptions, args: string[]) {
     )
     await fs.writeFile('/tmp/foundFiles.json', JSON.stringify(foundFiles, undefined, 2), 'utf-8')
   }
-  const searchFiles = [...new Set(foundFiles)] // filters out dupes
+  const searchFiles = [...new Set(foundFiles)]
     .filter((file) => endsWithAny(['.rb', '.yml', '.yaml', '.txt', '.pdf', '.erb', '.js'], file))
     .filter(
       (file) =>
diff --git a/src/links/scripts/check-links-external.ts b/src/links/scripts/check-links-external.ts
index fad3f210f0be..915c2360904f 100644
--- a/src/links/scripts/check-links-external.ts
+++ b/src/links/scripts/check-links-external.ts
@@ -35,17 +35,14 @@ import github from '@/workflows/github'
 import excludedLinks from '@/links/lib/excluded-links'
 import * as coreLib from '@actions/core'
 
-// Cache configuration
 const CACHE_FILE = process.env.EXTERNAL_LINK_CACHE_FILE || 'external-link-cache.json'
 const CACHE_MAX_AGE_DAYS = parseInt(process.env.CACHE_MAX_AGE_DAYS || '7', 10)
 const CACHE_MAX_AGE_MS = CACHE_MAX_AGE_DAYS * 24 * 60 * 60 * 1000
 
-// Request configuration
-const REQUEST_TIMEOUT_MS = 30000 // 30 seconds
-const REQUEST_DELAY_MS = 100 // 100ms between requests to avoid rate limiting
-const DEFAULT_DOMAIN_CONCURRENCY = 10 // Process this many domains in parallel
+const REQUEST_TIMEOUT_MS = 30000
+const REQUEST_DELAY_MS = 100 // Avoids rate limiting a single domain.
+const DEFAULT_DOMAIN_CONCURRENCY = 10
 
-// Create a set for fast lookups of excluded links
 const excludedLinksSet = new Set(excludedLinks.map(({ is }) => is).filter(Boolean))
 const excludedLinksPrefixes = excludedLinks.map(({ startsWith }) => startsWith).filter(Boolean)
 
@@ -54,7 +51,6 @@ function isExcludedLink(href: string): boolean {
   return excludedLinksPrefixes.some((prefix) => prefix && href.startsWith(prefix))
 }
 
-// Cache type
 interface CacheEntry {
   timestamp: number
   ok: boolean
@@ -81,9 +77,7 @@ interface LinkOccurrence {
  * are treated as the same URL.
  */
 function normalizeUrl(href: string): string {
-  // Remove fragment
   const withoutFragment = href.split('#')[0]
-  // Remove trailing slash only for origin/root URLs
   try {
     const parsed = new URL(withoutFragment)
     if (parsed.pathname === '/' && !parsed.search) {
@@ -103,22 +97,14 @@ function isDocsGithubUrl(url: string): boolean {
   }
 }
 
-/**
- * Sleep for a given number of milliseconds
- */
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
-/**
- * Check a single external URL
- * Uses HEAD first, falls back to GET if HEAD returns 4xx/5xx
- */
 async function checkUrl(
   url: string,
   cache: CacheData,
 ): Promise<{ ok: boolean; statusCode?: number; error?: string; cached: boolean }> {
-  // Check cache first
   const cached = cache.urls[url]
   if (cached) {
     const age = Date.now() - cached.timestamp
@@ -138,7 +124,6 @@ async function checkUrl(
   }
 
   if (!response) {
-    // Timeout or network error
     return { ok: false, error: 'Request timed out or failed', cached: false }
   }
 
@@ -149,7 +134,6 @@ async function checkUrl(
     cached: false,
   }
 
-  // Update cache
   cache.urls[url] = {
     timestamp: Date.now(),
     ok: result.ok,
@@ -160,9 +144,6 @@ async function checkUrl(
   return result
 }
 
-/**
- * Fetch with timeout, returns null on error
- */
 async function fetchWithTimeout(
   url: string,
   method: 'HEAD' | 'GET',
@@ -218,7 +199,6 @@ async function checkGithubRepoUrl(
   cached: boolean
   fallbackAllowed?: boolean
 }> {
-  // Check cache first
   const cached = cache.urls[url]
   if (cached) {
     const age = Date.now() - cached.timestamp
@@ -314,13 +294,9 @@ async function checkGithubRepoUrl(
   }
 }
 
-/**
- * Extract all external links from content files
- */
 async function extractAllExternalLinks(): Promise<Map<string, LinkOccurrence[]>> {
   const links = new Map<string, LinkOccurrence[]>()
 
-  // Find all Markdown files
   const files = await glob('content/**/*.md', { ignore: '**/README.md' })
   console.log(`Found ${files.length} Markdown files to scan`)
 
@@ -332,17 +308,15 @@ async function extractAllExternalLinks(): Promise<Map<string, LinkOccurrence[]>>
     const result = extractLinksFromMarkdown(content)
     const fileMs = Date.now() - fileStart
 
-    // Warn if a single file takes longer than 1 second (possible regex issue)
+    // A slow file may mean a pathological regex in the extractor.
     if (fileMs > 1000) {
       console.warn(`  ⚠️  Slow extraction: ${file} took ${(fileMs / 1000).toFixed(1)}s`)
     }
 
     for (const link of result.externalLinks) {
-      // Only check HTTPS links
       if (!link.href.startsWith('https://')) continue
       if (isExcludedLink(link.href)) continue
 
-      // Normalize URL (remove anchors and trailing slashes for checking)
       const url = normalizeUrl(link.href)
 
       if (!links.has(url)) {
@@ -363,9 +337,6 @@ async function extractAllExternalLinks(): Promise<Map<string, LinkOccurrence[]>>
   return links
 }
 
-/**
- * Main entry point
- */
 async function main() {
   program
     .name('check-links-external')
@@ -386,12 +357,10 @@ async function main() {
   console.log(chalk.blue('🌐 External Link Checker'))
   console.log('')
 
-  // Load cache
   const defaultData: CacheData = { urls: {} }
   const db = await JSONFilePreset<CacheData>(CACHE_FILE, defaultData)
   await db.read()
 
-  // Report cache stats
   const now = Date.now()
   let freshCount = 0
   let staleCount = 0
@@ -405,12 +374,11 @@ async function main() {
   console.log(`Cache: ${freshCount} fresh, ${staleCount} stale entries`)
   console.log('')
 
-  // Extract all external links
   console.log('Extracting external links from content files...')
   const allLinks = await extractAllExternalLinks()
 
-  // Separate docs.github.com links — they're self-referential (this repo IS the docs site)
-  // and will be reported separately as candidates for conversion to internal links.
+  // Separate docs.github.com links. They're self-referential, since this repo is the docs
+  // site, and get reported separately as candidates for conversion to internal links.
   const selfReferentialLinks = new Map<string, LinkOccurrence[]>()
   for (const [url, occurrences] of allLinks) {
     if (isDocsGithubUrl(url)) {
@@ -425,7 +393,6 @@ async function main() {
 
   if (options.dryRun) {
     console.log('Dry run mode - not checking URLs')
-    // Show sample of URLs
     const sample = Array.from(allLinks.keys()).slice(0, 20)
     for (const url of sample) {
       console.log(`  ${url}`)
@@ -436,7 +403,6 @@ async function main() {
     process.exit(0)
   }
 
-  // Check URLs
   const brokenLinks: BrokenLink[] = []
   let checkedCount = 0
   let cachedCount = 0
@@ -459,7 +425,6 @@ async function main() {
       if (!urlsByDomain.has(hostname)) urlsByDomain.set(hostname, [])
       urlsByDomain.get(hostname)!.push(url)
     } catch {
-      // Record malformed URLs as broken links
       malformedCount++
       checkedCount++
       const occurrences = allLinks.get(url)!
@@ -529,7 +494,6 @@ async function main() {
         console.log(`  ✅ ${url}`)
       }
 
-      // Progress update every 100 URLs
       if (checkedCount % 100 === 0) {
         const elapsed = ((Date.now() - startTime) / 1000).toFixed(0)
         const rate = (checkedCount / (Date.now() - startTime)) * 1000 * 60
@@ -540,7 +504,6 @@ async function main() {
         )
       }
 
-      // Small delay between requests to the same domain to avoid rate limiting
       if (!result.cached) {
         await sleep(REQUEST_DELAY_MS)
       }
@@ -564,17 +527,14 @@ async function main() {
 
   await Promise.all(workers.map(runWorker))
 
-  // Save cache
   await db.write()
 
-  // Report results
   const duration = ((Date.now() - startTime) / 1000).toFixed(1)
   console.log('')
   console.log(
     chalk.blue(`Checked ${checkedCount} URLs in ${duration}s (${cachedCount} from cache)`),
   )
 
-  // Build self-referential BrokenLink list for the report
   const selfReferentialBrokenLinks: BrokenLink[] = []
   for (const occurrences of selfReferentialLinks.values()) {
     for (const occ of occurrences) {
@@ -587,7 +547,6 @@ async function main() {
     process.exit(0)
   }
 
-  // Generate report
   const report = generateExternalLinkReport(brokenLinks, {
     actionUrl: process.env.ACTION_RUN_URL,
     selfReferentialLinks: selfReferentialBrokenLinks,
@@ -605,7 +564,6 @@ async function main() {
     console.log(chalk.red(`❌ ${report.uniqueTargets} domain(s) with broken links`))
     console.log(chalk.red(`   ${report.totalOccurrences} total occurrence(s)`))
 
-    // Show summary by domain
     console.log('')
     console.log('Broken links by domain:')
     for (const group of report.groups.slice(0, 10)) {
@@ -616,12 +574,10 @@ async function main() {
     }
   }
 
-  // Write artifact
   const markdown = reportToMarkdown(report, true)
   await uploadArtifact('external-link-report.md', markdown)
   await uploadArtifact('external-link-report.json', JSON.stringify(report, null, 2))
 
-  // Create issue report if configured
   const createReport = process.env.CREATE_REPORT === 'true'
   const reportRepository = process.env.REPORT_REPOSITORY || 'github/docs-content'
 
@@ -642,7 +598,6 @@ async function main() {
       reportLabel,
     })
 
-    // Link to previous reports
     await linkReports({
       core: coreLib,
       octokit,
@@ -656,7 +611,6 @@ async function main() {
   }
 }
 
-// Run if invoked directly
 ;(async () => {
   try {
     await main()
diff --git a/src/links/scripts/check-links-internal.ts b/src/links/scripts/check-links-internal.ts
index c298d98066ff..3de89ec9b7dc 100644
--- a/src/links/scripts/check-links-internal.ts
+++ b/src/links/scripts/check-links-internal.ts
@@ -56,7 +56,6 @@ import { getFeaturesByVersion } from '@/versions/middleware/features'
 import type { Page, Permalink, Context } from '@/types'
 import * as coreLib from '@actions/core'
 
-// Create a set for fast lookups of excluded links
 const excludedLinksSet = new Set(excludedLinks.map(({ is }) => is).filter(Boolean))
 const excludedLinksPrefixes = excludedLinks.map(({ startsWith }) => startsWith).filter(Boolean)
 
@@ -78,7 +77,7 @@ interface CheckResult {
  * parsing are relative to the body. Adding this offset converts them to
  * actual file line numbers.
  *
- * Results are cached by fullPath — the file is read once per page across
+ * Results are cached by fullPath, so the file is read once per page across
  * both getLinksFromMarkdown() and checkAnchorsOnPage().
  */
 const frontmatterLineOffsetCache = new Map<string, number>()
@@ -103,7 +102,7 @@ function getFrontmatterLineOffset(fullPath: string): number {
       }
     }
   } catch {
-    // ignore — fall back to no offset
+    // Ignore: fall back to no offset.
   }
 
   frontmatterLineOffsetCache.set(fullPath, offset)
@@ -155,7 +154,7 @@ async function getLinksFromMarkdown(
         // extractLinksWithLiquid will produce, without affecting line positions.
         canonicalHref = (await renderLiquidFn(canonicalHref, context)).trim()
       } catch {
-        // fall back to raw href if rendering fails
+        // Fall back to the raw href if rendering fails.
       }
     }
     const existing = rawLinesByHref.get(canonicalHref)
@@ -182,7 +181,7 @@ async function getLinksFromMarkdown(
           }
         }
       } catch {
-        // skip — can't resolve line number for this link
+        // Skip: can't resolve a line number for this link.
       }
     }
   }
@@ -236,7 +235,7 @@ function checkAnchorsFromHeadings(
   }
 
   // Check only the anchor links that actually appear in the Liquid-rendered output
-  // (respects {% ifversion %} gates — links in non-applicable blocks are not checked).
+  // (respects {% ifversion %} gates, so links in non-applicable blocks are not checked).
   const brokenAnchors: BrokenLink[] = []
   for (const link of renderedResult.anchorLinks) {
     const { href } = link
@@ -288,7 +287,7 @@ async function checkPage(
 
   // Compute this page's heading anchor IDs once from the Liquid-rendered markdown.
   // Autogenerated pages (REST/GraphQL/webhooks) derive their anchors from OpenAPI
-  // operation IDs, not markdown headings, so we can't compute them here — leave them
+  // operation IDs, not markdown headings, so we can't compute them here. Leave them
   // out of the cache so links into them are never flagged (they resolve at runtime).
   // Skip the work entirely when anchor checking is disabled: nothing downstream reads
   // the heading cache in that mode.
@@ -300,7 +299,6 @@ async function checkPage(
   for (const link of links) {
     if (isExcludedLink(link.href)) continue
 
-    // Check if this is an asset link (images, etc.) - verify file exists on disk
     if (isAssetLink(link.href)) {
       if (!checkAssetLink(link.href)) {
         brokenLinks.push({
@@ -392,7 +390,6 @@ async function checkVersion(
     throw new Error(`Unknown version: ${version}`)
   }
 
-  // Filter pages for this version and language
   const relevantPages = pageList.filter((page) => {
     if (page.languageCode !== language) return false
     if (!page.applicableVersions?.includes(version)) return false
@@ -403,7 +400,8 @@ async function checkVersion(
     `  Checking ${relevantPages.length} pages for ${version}/${language} (concurrency: ${options.concurrency})`,
   )
 
-  // Build a base context once per version — feature flags and version info are the same for all pages.
+  // Build a base context once per version: feature flags and version info are the same
+  // for all pages.
   // Each page gets a shallow copy so concurrent tasks don't share the mutable `page` property.
   const baseContext = {
     currentVersion: version,
@@ -421,10 +419,10 @@ async function checkVersion(
   let totalLinksChecked = 0
 
   // Cross-page anchor validation is a two-pass process within the version:
-  //   pass 1 — render every page, caching its heading IDs and collecting the
-  //            cross-page anchor links it contains (target may not be rendered yet)
-  //   pass 2 — after all pages are rendered, validate each collected anchor against
-  //            the now-complete heading cache
+  //   pass 1: render every page, caching its heading IDs and collecting the
+  //           cross-page anchor links it contains (target may not be rendered yet)
+  //   pass 2: after all pages are rendered, validate each collected anchor against
+  //           the now-complete heading cache
   // The cache is keyed by pageMap key (lang + version + path). A link whose target
   // resolves to a different version isn't in this run's cache and is skipped here;
   // it's validated when the workflow runs the checker for that target version.
@@ -432,7 +430,7 @@ async function checkVersion(
   const pendingCrossPageAnchors: PendingCrossPageAnchor[] = []
 
   // Bounded concurrency: process up to `options.concurrency` pages simultaneously.
-  // All workers drain from the same shared iterator — no page is processed twice.
+  // All workers drain from the same shared iterator, so no page is processed twice.
   const queue = relevantPages.entries()
 
   async function worker() {
@@ -483,9 +481,6 @@ async function checkVersion(
   }
 }
 
-/**
- * Main entry point
- */
 async function main() {
   program
     .name('check-links-internal')
@@ -508,7 +503,6 @@ async function main() {
   console.log(chalk.blue('🔗 Internal Link Checker'))
   console.log('')
 
-  // Determine version and language to check
   const version = options.version || process.env.VERSION
   const language = options.language || process.env.LANGUAGE || 'en'
   const checkAnchors = options.checkAnchors && process.env.CHECK_ANCHORS !== 'false'
@@ -536,13 +530,11 @@ async function main() {
   console.log(`Check anchors: ${checkAnchors}`)
   console.log('')
 
-  // Load page data
   console.log('Loading page data...')
   const { pages: pageMap, redirects, pageList } = await warmServer([language])
   console.log(`Loaded ${pageList.length} pages, ${Object.keys(redirects).length} redirects`)
   console.log('')
 
-  // Run the check
   const concurrency = Math.max(1, parseInt(process.env.CONCURRENCY || options.concurrency, 10))
   const result = await checkVersion(version, language, pageList, pageMap, redirects, {
     checkAnchors,
@@ -550,7 +542,6 @@ async function main() {
     concurrency,
   })
 
-  // Report results
   const duration = ((Date.now() - startTime) / 1000).toFixed(1)
   console.log('')
   console.log(
@@ -566,7 +557,6 @@ async function main() {
     process.exit(0)
   }
 
-  // Generate report
   const report = generateInternalLinkReport(allBrokenLinks, {
     actionUrl: process.env.ACTION_RUN_URL,
     version,
@@ -578,12 +568,10 @@ async function main() {
   console.log(chalk.red(`❌ ${result.brokenLinks.length} broken link(s)`))
   console.log(chalk.yellow(`⚠️  ${result.redirectLinks.length} redirect(s) to update`))
 
-  // Write artifact
   const markdown = reportToMarkdown(report)
   await uploadArtifact(`link-report-${version}-${language}.md`, markdown)
   await uploadArtifact(`link-report-${version}-${language}.json`, JSON.stringify(report, null, 2))
 
-  // Create issue report if configured
   const createReport = process.env.CREATE_REPORT === 'true'
   const reportRepository = process.env.REPORT_REPOSITORY || 'github/docs-content'
 
@@ -604,7 +592,6 @@ async function main() {
       reportLabel,
     })
 
-    // Link to previous reports
     await linkReports({
       core: coreLib,
       octokit,
@@ -617,8 +604,8 @@ async function main() {
     console.log(`Created report issue: ${newReport.html_url}`)
   }
 
-  // Don't exit with error - the issue report is the mechanism for docs-content to act on broken links
-  // Exiting with error would trigger docs-alerts which only engineering monitors
+  // Don't exit with an error. The issue report is how docs-content hears about broken
+  // links, whereas a failing exit code only triggers docs-alerts.
   console.log('')
   console.log(
     chalk.yellow(
@@ -627,7 +614,6 @@ async function main() {
   )
 }
 
-// Run if invoked directly
 ;(async () => {
   try {
     await main()
diff --git a/src/links/scripts/check-links-pr.ts b/src/links/scripts/check-links-pr.ts
index cebeefc61706..cab25e865218 100644
--- a/src/links/scripts/check-links-pr.ts
+++ b/src/links/scripts/check-links-pr.ts
@@ -57,9 +57,6 @@ interface CheckResult {
   totalLinksChecked: number
 }
 
-/**
- * Check all internal links in a single file
- */
 async function checkFile(
   filePath: string,
   pageMap: Record<string, Page>,
@@ -71,7 +68,6 @@ async function checkFile(
   const redirectLinks: BrokenLink[] = []
   let totalLinksChecked = 0
 
-  // Read file content
   let content: string
   try {
     content = fs.readFileSync(filePath, 'utf-8')
@@ -80,17 +76,14 @@ async function checkFile(
     return { file: filePath, brokenLinks, redirectLinks, totalLinksChecked }
   }
 
-  // Create context for Liquid rendering
   const context = createLiquidContext(version, language)
 
-  // Extract links after Liquid rendering
   const { internalLinks } = await extractLinksWithLiquid(content, context)
 
-  // Check each internal link (exclude imageLinks - they're static assets, not docs pages)
+  // imageLinks are excluded: they're static assets, not docs pages.
   totalLinksChecked = internalLinks.length
 
   for (const link of internalLinks) {
-    // Check if this is an asset link (images, etc.) - verify file exists on disk
     if (isAssetLink(link.href)) {
       if (!checkAssetLink(link.href)) {
         brokenLinks.push({
@@ -181,7 +174,7 @@ async function checkFileAnchors(
       if (link.fragment === 'top') continue
 
       // resolveLinkKeyForVersion only returns direct (non-redirect) page hits, so
-      // redirects, archived versions, and broken paths fall out here — they're not
+      // redirects, archived versions, and broken paths fall out here. They're not
       // anchor-scope flaws. Unversioned hrefs are retried against the version the source
       // page is currently rendered in, so GHEC/GHES-only targets resolve too.
       const targetKey = resolveLinkKeyForVersion(link.href, version, pageMap)
@@ -235,7 +228,6 @@ function getChangedFiles(cliFiles?: string[]): string[] {
     return cliFiles
   }
 
-  // Check environment variable (from GitHub Actions)
   const filesChanged = process.env.FILES_CHANGED
   if (filesChanged) {
     // Try parsing as JSON first
@@ -253,12 +245,8 @@ function getChangedFiles(cliFiles?: string[]): string[] {
   return []
 }
 
-/**
- * Filter to only content/data files that might contain links
- */
 function filterContentFiles(files: string[]): string[] {
   return files.filter((file) => {
-    // Only check Markdown files in content/ or data/
     if (!file.endsWith('.md')) return false
     // Skip README.md files. They're developer docs, not published pages, and use
     // repo-relative paths (e.g. /src/...) that aren't valid site links.
@@ -268,9 +256,6 @@ function filterContentFiles(files: string[]): string[] {
   })
 }
 
-/**
- * Post a comment on the PR with broken link results
- */
 async function commentOnPR(
   brokenLinks: BrokenLink[],
   brokenAnchors: CrossPageAnchorFlaw[],
@@ -346,9 +331,6 @@ async function commentOnPR(
   }
 }
 
-/**
- * Main entry point
- */
 async function main() {
   program
     .name('check-links-pr')
@@ -364,7 +346,6 @@ async function main() {
   console.log(chalk.blue('🔗 PR Link Checker'))
   console.log('')
 
-  // Get files to check
   let files = getChangedFiles(options.files)
 
   if (options.all) {
@@ -377,7 +358,6 @@ async function main() {
     process.exit(0)
   }
 
-  // Filter to content files only
   const contentFiles = filterContentFiles(files)
   if (contentFiles.length === 0) {
     console.log('No content files in changed files. Exiting.')
@@ -386,7 +366,6 @@ async function main() {
 
   console.log(`Checking ${contentFiles.length} file(s)...`)
 
-  // Load page data
   console.log('Loading page data...')
   const { pages: pageMap, pageList, redirects } = await warmServer(['en'])
   console.log(
@@ -405,7 +384,6 @@ async function main() {
   const checkAnchors = process.env.CHECK_ANCHORS !== 'false'
   const headingCache = new Map<string, Set<string>>()
 
-  // Check each file
   const allBrokenLinks: BrokenLink[] = []
   const allRedirectLinks: BrokenLink[] = []
   const allBrokenAnchors: CrossPageAnchorFlaw[] = []
@@ -437,7 +415,6 @@ async function main() {
     }
   }
 
-  // Report results
   const duration = ((Date.now() - startTime) / 1000).toFixed(1)
   console.log('')
   console.log(chalk.blue(`Checked ${totalLinksChecked} links in ${duration}s`))
@@ -459,7 +436,6 @@ async function main() {
     process.exit(0)
   }
 
-  // Group and display results
   if (allBrokenLinks.length > 0) {
     console.log('')
     console.log(chalk.red(`❌ ${allBrokenLinks.length} broken link(s):`))
@@ -537,7 +513,6 @@ async function main() {
   }
 }
 
-// Run if invoked directly
 ;(async () => {
   try {
     await main()
diff --git a/src/links/scripts/debug-time-taken.ts b/src/links/scripts/debug-time-taken.ts
index c8e7d53cd8ce..f6b11dc15172 100644
--- a/src/links/scripts/debug-time-taken.ts
+++ b/src/links/scripts/debug-time-taken.ts
@@ -2,7 +2,7 @@ const timeInstances = new Map()
 
 type CoreLike = { warning: (message: string | Error) => void; debug: (message: string) => void }
 
-/* Meant to be called before debugTimeEnd with the same instanceName to behave like console.time() */
+// Pair with debugTimeEnd using the same instanceName, like console.time().
 export function debugTimeStart(core: CoreLike, instanceName: string) {
   if (timeInstances.has(instanceName)) {
     core.warning(`instanceName: ${instanceName} has already been used for a debug instance.`)
@@ -12,7 +12,7 @@ export function debugTimeStart(core: CoreLike, instanceName: string) {
   timeInstances.set(instanceName, new Date())
 }
 
-/* Meant to be called after debugTimeStart with the same instanceName to behave like console.timeEnd() */
+// Pair with debugTimeStart using the same instanceName, like console.timeEnd().
 export function debugTimeEnd(core: CoreLike, instanceName: string) {
   if (!timeInstances.has(instanceName)) {
     core.warning(
diff --git a/src/links/scripts/upload-artifact.ts b/src/links/scripts/upload-artifact.ts
index 3b1fba48dd0f..b37beb31103a 100644
--- a/src/links/scripts/upload-artifact.ts
+++ b/src/links/scripts/upload-artifact.ts
@@ -1,11 +1,7 @@
 import fs from 'fs'
 
-/* Writes string to file to be uploaded as an action artifact.
- * Useful for debugging or passing results to downstream action
- *
- * @param {string} name - name of artifact
- * @param {string} contents - string contents of artifact
- */
+// Writes a string to a file for the workflow to upload as an artifact.
+// Useful for debugging, or for passing results to a downstream action.
 export async function uploadArtifact(name: string, contents: string) {
   if (!fs.existsSync('./artifacts')) {
     fs.mkdirSync('./artifacts/')
diff --git a/src/links/scripts/validate-github-github-docs-urls/post-pr-comment.ts b/src/links/scripts/validate-github-github-docs-urls/post-pr-comment.ts
index c02e4e368ade..4b2d38a1786b 100644
--- a/src/links/scripts/validate-github-github-docs-urls/post-pr-comment.ts
+++ b/src/links/scripts/validate-github-github-docs-urls/post-pr-comment.ts
@@ -21,7 +21,6 @@ type PostPRCommentOptions = {
 
 // This function is designed to be able to run and potentially do nothing.
 export async function postPRComment(filePath: string, options: PostPRCommentOptions) {
-  // Check the options before we even begin
   if (!options.dryRun) {
     if (!options.issueNumber) {
       throw new Error(
@@ -258,11 +257,10 @@ async function updateIssueComment(
     }
   }
 
-  // It found no comment to *edit*, so it create *create* a new comment.
-  // But `onlyIfAlreadyPosted` is true, so it does nothing.
-  // This is convenient when might have, during the lifetime of a PR,
-  // posted a comment, then committed more changes, and then realize
-  // that what was posted previously is no long the case.
+  // There is no comment to edit, so this would create one, but `onlyIfAlreadyPosted`
+  // is true so it does nothing. That matters when a PR previously had failing checks,
+  // got more commits, and no longer does: the old comment should be updated, but a
+  // PR that never failed should not gain one.
   if (onlyIfAlreadyPosted) {
     console.warn(`Deliberately not creating a new comment`)
     return
diff --git a/src/links/scripts/validate-github-github-docs-urls/validate.ts b/src/links/scripts/validate-github-github-docs-urls/validate.ts
index 8c5824c1d386..f6e9fb5ef081 100644
--- a/src/links/scripts/validate-github-github-docs-urls/validate.ts
+++ b/src/links/scripts/validate-github-github-docs-urls/validate.ts
@@ -27,7 +27,7 @@ export async function validate(filePath: string, options: Options) {
         console.log(prefix, `✅ ${check.url} (${check.identifier})`)
       }
     } else {
-      // This is a 404 - page not found
+      // A 404: the page does not exist.
       if (options.ignoreNotFound) {
         console.log(prefix, `⚠️  ${check.url} (${check.identifier})`)
       } else {

From f1114fe1eba491c5cf6303094ef0d7458cc7662a Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:16:59 +0000
Subject: [PATCH 05/16] Trim excessive comments in src/languages (#63268)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/languages/components/LanguagePicker.tsx   |  2 +-
 src/languages/lib/get-english-headings.ts     |  1 -
 src/languages/lib/languages-server.ts         | 21 ++++++++-----------
 src/languages/lib/languages.ts                |  2 +-
 src/languages/lib/render-with-fallback.ts     |  9 --------
 src/languages/lib/translation-utils.ts        |  7 +------
 .../scripts/count-translation-corruptions.ts  | 12 +++++------
 .../tests/count-translation-corruptions.ts    |  4 ++--
 .../tests/translation-error-comments.ts       |  7 +------
 9 files changed, 21 insertions(+), 44 deletions(-)

diff --git a/src/languages/components/LanguagePicker.tsx b/src/languages/components/LanguagePicker.tsx
index 05c46694d8a9..c6c69b2b9a98 100644
--- a/src/languages/components/LanguagePicker.tsx
+++ b/src/languages/components/LanguagePicker.tsx
@@ -25,7 +25,7 @@ export const LanguagePicker = ({ xs, mediumOrLower }: Props) => {
   // that are available.
   // Also, if the current context has a page and that page has own ideas
   // about which languages it's available in (e.g. early-access)
-  // it would already have been paired down.
+  // it would already have been pared down.
   const langs = Object.values(languages)
 
   if (langs.length < 2) {
diff --git a/src/languages/lib/get-english-headings.ts b/src/languages/lib/get-english-headings.ts
index 470286078a5d..fa8362f0f72b 100644
--- a/src/languages/lib/get-english-headings.ts
+++ b/src/languages/lib/get-english-headings.ts
@@ -54,7 +54,6 @@ export default function getEnglishHeadings(
   const englishHeadings = getHeadings(englishPage.markdown)
   if (!englishHeadings.length) return
 
-  // return a map from translation:English
   const headingMap: Record<string, string> = {}
   for (let i = 0; i < translatedHeadings.length; i++) {
     const k = translatedHeadings[i]
diff --git a/src/languages/lib/languages-server.ts b/src/languages/lib/languages-server.ts
index da2fa046e3a5..fcd6b84adc23 100644
--- a/src/languages/lib/languages-server.ts
+++ b/src/languages/lib/languages-server.ts
@@ -1,10 +1,8 @@
-/*
-This file adds the following properties to languages in ./languages.ts:
-- dir: string
-
-This file will also remove languages for local development and tests
-that have not be specified by ENABLED_LANGUAGES
-*/
+// Adds a `dir` property to each language in ./languages.ts.
+//
+// Also narrows the set of languages, in this order: to whatever has a
+// directory under TRANSLATIONS_FIXTURE_ROOT, else to ENABLED_LANGUAGES, else
+// to English alone when NODE_ENV is 'test'.
 
 import path from 'path'
 import fs from 'fs'
@@ -15,7 +13,6 @@ import { languages as baseLanguages, type Language as BaseLanguage } from './lan
 
 dotenv.config({ quiet: true })
 
-// Server-side language extends base language with required dir property
 export interface Language extends BaseLanguage {
   dir: string
 }
@@ -45,7 +42,6 @@ function getRoot(languageCode: string): string {
   return path.join(TRANSLATIONS_ROOT, languageCode)
 }
 
-// Build server languages with directory paths
 const allLanguagesWithDirs: Languages = {}
 for (const [code, lang] of Object.entries(baseLanguages)) {
   allLanguagesWithDirs[code] = {
@@ -86,9 +82,10 @@ export const languageKeys: string[] = Object.keys(languages)
 
 export const languagePrefixPathRegex: RegExp = new RegExp(`^/(${languageKeys.join('|')})(/|$)`)
 
-/** Return true if the URL is something like /en/foo or /ja but return false
- * if it's something like /foo or /foo/bar or /fr (because French (fr)
- * is currently not an active language)
+/** Return true if the URL starts with a currently active language code, e.g.
+ * /en/foo or /ja. Returns false for /foo or /foo/bar. Which codes count as
+ * active depends on TRANSLATIONS_FIXTURE_ROOT, ENABLED_LANGUAGES, and
+ * NODE_ENV, so this varies between production, local dev, and tests.
  */
 export function pathLanguagePrefixed(urlPath: string): boolean {
   return languagePrefixPathRegex.test(urlPath)
diff --git a/src/languages/lib/languages.ts b/src/languages/lib/languages.ts
index ba319f697b4b..d8d16cb3278c 100644
--- a/src/languages/lib/languages.ts
+++ b/src/languages/lib/languages.ts
@@ -1,5 +1,5 @@
 // See also languages-schema.ts
-// Nota bene: If you are adding a new language,
+// Note: if you are adding a new language,
 // change accept-language handling in CDN config as well.
 
 /**
diff --git a/src/languages/lib/render-with-fallback.ts b/src/languages/lib/render-with-fallback.ts
index a1bcd4f1b17e..d07e57645436 100644
--- a/src/languages/lib/render-with-fallback.ts
+++ b/src/languages/lib/render-with-fallback.ts
@@ -56,14 +56,11 @@ export function createTranslationFallbackComment(error: Error, property: string)
   const errorType = error.name || 'UnknownError'
   const errorDetails: string[] = []
 
-  // Add basic error information
   errorDetails.push(`TRANSLATION_FALLBACK`)
   errorDetails.push(`prop=${property}`)
   errorDetails.push(`type=${errorType}`)
 
-  // Extract detailed error information based on error type
   if (isLiquidError(error)) {
-    // For Liquid errors, we can extract rich debugging information
     if (error.token) {
       if (error.token.file) {
         errorDetails.push(`file=${error.token.file}`)
@@ -75,13 +72,10 @@ export function createTranslationFallbackComment(error: Error, property: string)
       }
     }
 
-    // Include the original error message if available
     const originalMessage = error.originalError?.message || error.message
     if (originalMessage) {
-      // Clean up the message but keep useful information
       let cleanMessage = originalMessage.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim()
 
-      // Limit message length to keep comment manageable
       if (cleanMessage.length > 200) {
         cleanMessage = `${cleanMessage.substring(0, 200)}...`
       }
@@ -89,7 +83,6 @@ export function createTranslationFallbackComment(error: Error, property: string)
       errorDetails.push(`msg="${cleanMessage.replace(/"/g, "'")}"`)
     }
   } else if (isAutotitleError(error)) {
-    // For AUTOTITLE errors, include the error message
     if (error.message) {
       const cleanMessage = error.message
         .replace(/\n/g, ' ')
@@ -99,7 +92,6 @@ export function createTranslationFallbackComment(error: Error, property: string)
       errorDetails.push(`msg="${cleanMessage.replace(/"/g, "'")}"`)
     }
   } else if (isEmptyTitleError(error)) {
-    // For empty title errors, include the property info
     errorDetails.push(`msg="Content became empty after rendering"`)
   }
 
@@ -148,7 +140,6 @@ export async function renderContentWithFallback(
       // like `data.ts` that uses `environment.scope.currentLanguage`
       const enContext = Object.assign({}, context, { currentLanguage: 'en' })
 
-      // Render the English fallback content
       const fallbackContent = await renderContent(englishTemplate, enContext, options)
 
       // Add HTML comment with error details for non-English languages
diff --git a/src/languages/lib/translation-utils.ts b/src/languages/lib/translation-utils.ts
index 56f31fdcefd0..2e2273d2866b 100644
--- a/src/languages/lib/translation-utils.ts
+++ b/src/languages/lib/translation-utils.ts
@@ -50,7 +50,7 @@ export function createTranslationFunctions(uiData: UIStrings, namespaces: string
       // Try each namespace in order
       for (const namespace of namespacesArray) {
         if (!(namespace in uiData)) {
-          continue // Skip missing namespaces
+          continue
         }
         const deeper = uiData[namespace]
         if (typeof deeper === 'string') {
@@ -105,7 +105,6 @@ export function createTranslationFunctions(uiData: UIStrings, namespaces: string
  * Enhanced with better error handling for missing keys and defensive fallbacks
  */
 export function translate(uiData: UIStrings, key: string, fallback?: string): string {
-  // Defensive check for completely missing data
   if (!uiData || typeof uiData !== 'object') {
     console.warn(`UI data is missing or corrupted for key "${key}", using fallback`)
     return getCommonFallback(key, fallback)
@@ -116,7 +115,6 @@ export function translate(uiData: UIStrings, key: string, fallback?: string): st
   } catch (error) {
     const finalFallback = getCommonFallback(key, fallback)
 
-    // Only warn in development
     if (process.env.NODE_ENV === 'development') {
       console.warn(
         `Server translation failed for "${key}":`,
@@ -129,9 +127,6 @@ export function translate(uiData: UIStrings, key: string, fallback?: string): st
   }
 }
 
-/**
- * Get common fallback values for essential UI keys
- */
 function getCommonFallback(key: string, providedFallback?: string): string {
   const commonFallbacks: Record<string, string> = {
     'meta.oops': 'Ooops!',
diff --git a/src/languages/scripts/count-translation-corruptions.ts b/src/languages/scripts/count-translation-corruptions.ts
index d629fa886cab..3e0944935c9b 100644
--- a/src/languages/scripts/count-translation-corruptions.ts
+++ b/src/languages/scripts/count-translation-corruptions.ts
@@ -206,7 +206,7 @@ async function run(
   // version it surfaced under (rather than N near-duplicate entries).
   const byKey = new Map<string, CorruptionEntry & { versionSet: Set<string> }>()
 
-  // Suppress console.warn during rendering — the {% data %} tag warns
+  // Suppress console.warn during rendering. The {% data %} tag warns
   // when it can't find translated data, which is expected noise.
   const originalWarn = console.warn
   console.warn = () => {}
@@ -242,9 +242,9 @@ async function run(
     for (const page of site.pageList) {
       if (page.languageCode !== languageCode) continue
 
-      // Only render under versions the page is actually served in (intersected
-      // with the requested set) — a page is never scraped under a version it
-      // doesn't apply to, so corruptions there can't break indexing.
+      // Only render under versions the page is actually served in, intersected
+      // with the requested set. A page is never scraped under a version it does
+      // not apply to, so corruptions there cannot break indexing.
       const pageVersions = versions.filter((v) => page.applicableVersions.includes(v))
       if (!pageVersions.length) continue
 
@@ -280,8 +280,8 @@ async function run(
           relativePath,
         })
       } catch (error) {
-        // A missing translated file (ENOENT) just means this language hasn't
-        // translated this reusable yet — skip it silently. Any other error (e.g.
+        // A missing translated file (ENOENT) just means this language has not
+        // translated this reusable yet, so skip it silently. Any other error (e.g.
         // a malformed reusable that breaks correctTranslatedContentStrings) is a
         // real corruption: record it and keep going rather than crashing the run.
         if (error instanceof Error) {
diff --git a/src/languages/tests/count-translation-corruptions.ts b/src/languages/tests/count-translation-corruptions.ts
index b4117e82764e..1a1a8fe2f0e7 100644
--- a/src/languages/tests/count-translation-corruptions.ts
+++ b/src/languages/tests/count-translation-corruptions.ts
@@ -3,7 +3,7 @@ import { describe, expect, test } from 'vitest'
 import { allVersions } from '@/versions/lib/all-versions'
 import { resolveRequestedVersions } from '@/languages/scripts/count-translation-corruptions'
 
-// Pick a real GHES key at runtime rather than hard-coding one — allVersions
+// Pick a real GHES key at runtime rather than hard-coding one. allVersions
 // only contains currently-supported releases, so a literal like
 // `enterprise-server@3.16` would start failing once it rolls off support.
 const someGhesVersion = Object.keys(allVersions).find((v) => v.startsWith('enterprise-server@'))!
@@ -28,7 +28,7 @@ describe('resolveRequestedVersions', () => {
   })
 
   test('rejects versions that are not real allVersions keys', () => {
-    // `enterprise-server@latest` is a common mistake — it is not a real key.
+    // `enterprise-server@latest` is a common mistake. It is not a real key.
     expect(() => resolveRequestedVersions('enterprise-server@latest')).toThrow(
       /Invalid version\(s\): enterprise-server@latest/,
     )
diff --git a/src/languages/tests/translation-error-comments.ts b/src/languages/tests/translation-error-comments.ts
index af5986944f66..5e6d83c266a7 100644
--- a/src/languages/tests/translation-error-comments.ts
+++ b/src/languages/tests/translation-error-comments.ts
@@ -10,7 +10,6 @@ import { TitleFromAutotitleError } from '@/content-render/unified/rewrite-local-
 import Page from '@/frame/lib/page'
 
 describe('Translation Error Comments', () => {
-  // Mock renderContent for integration tests
   let mockRenderContent: MockedFunction<
     (template: string, context: Record<string, unknown>) => string
   >
@@ -179,7 +178,7 @@ describe('Translation Error Comments', () => {
       })
 
       test('truncates very long error messages', () => {
-        const longMessage = 'A'.repeat(300) // Very long error message
+        const longMessage = 'A'.repeat(300)
         const error = new LiquidError(longMessage, 'ParseError')
 
         const result = createTranslationFallbackComment(error, 'rawTitle')
@@ -223,7 +222,6 @@ describe('Translation Error Comments', () => {
 
         expect(result).toContain('type=ParseError')
         expect(result).toContain('prop=title')
-        // Should handle gracefully, might not have msg or have empty msg
       })
 
       test('cleans up multiline messages', () => {
@@ -246,11 +244,9 @@ describe('Translation Error Comments', () => {
 
         const result = createTranslationFallbackComment(error, 'rawTitle')
 
-        // Should be a proper HTML comment
         expect(result.startsWith('<!-- TRANSLATION_FALLBACK')).toBe(true)
         expect(result.endsWith('-->')).toBe(true)
 
-        // Should be on a single line
         expect(result).not.toContain('\n')
       })
 
@@ -281,7 +277,6 @@ describe('Translation Error Comments', () => {
 
         const result = createTranslationFallbackComment(error, 'title')
 
-        // Should follow the expected structure with all required fields
         expect(result.startsWith('<!-- TRANSLATION_FALLBACK')).toBe(true)
         expect(result).toContain('prop=title')
         expect(result).toContain('type=ParseError')

From d6f91cd69d867c5bd29739759ca92560a5bf4eb2 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:17:04 +0000
Subject: [PATCH 06/16] Trim excessive comments in src/content-linter scripts
 and tests (#63267)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/content-linter/scripts/disable-rules.ts   |  2 +-
 src/content-linter/scripts/generate-docs.ts   |  6 +-
 src/content-linter/scripts/lint-content.ts    | 64 +++++--------------
 src/content-linter/scripts/lint-report.ts     | 13 +---
 .../scripts/pretty-print-results.ts           |  4 +-
 src/content-linter/tests/category-pages.ts    |  9 +--
 .../tests/integration/lint-cli.ts             | 44 ++++---------
 src/content-linter/tests/lint-files.ts        |  4 +-
 .../tests/site-data-references.ts             |  4 +-
 src/content-linter/tests/unit/ctas-schema.ts  |  6 +-
 .../tests/unit/frontmatter-content-type.ts    |  6 +-
 .../unit/frontmatter-landing-carousels.ts     | 27 ++------
 .../tests/unit/frontmatter-schema.ts          |  2 +-
 .../tests/unit/frontmatter-search-replace.ts  |  4 --
 .../unit/frontmatter-versions-whitespace.ts   |  2 -
 .../unit/image-alt-text-end-punctuation.ts    |  5 +-
 .../image-alt-text-exclude-start-words.ts     |  5 +-
 .../tests/unit/internal-links-no-lang.ts      |  2 +-
 .../tests/unit/internal-links-old-version.ts  |  2 +-
 .../tests/unit/lint-report-exclusions.ts      |  1 -
 .../tests/unit/liquid-ifversion-versions.ts   |  3 +-
 .../tests/unit/liquid-syntax.ts               |  2 +-
 .../tests/unit/liquid-versioning.ts           |  2 +-
 .../tests/unit/rai-app-card-structure.ts      | 14 +---
 .../tests/unit/rule-filtering.ts              |  1 -
 .../tests/unit/search-replace.ts              |  2 -
 26 files changed, 61 insertions(+), 175 deletions(-)

diff --git a/src/content-linter/scripts/disable-rules.ts b/src/content-linter/scripts/disable-rules.ts
index a6210829e740..9d07356915ce 100755
--- a/src/content-linter/scripts/disable-rules.ts
+++ b/src/content-linter/scripts/disable-rules.ts
@@ -1,6 +1,6 @@
 // Disables markdownlint rules in markdown files with same-line comments. This is
 // useful when introducing a new rule that causes many failures. The comments
-// can be fixed and removed at while updating the file later.
+// can be fixed and removed while updating the file later.
 //
 // Usage:
 //
diff --git a/src/content-linter/scripts/generate-docs.ts b/src/content-linter/scripts/generate-docs.ts
index be11c3378252..c70ced85f2ba 100644
--- a/src/content-linter/scripts/generate-docs.ts
+++ b/src/content-linter/scripts/generate-docs.ts
@@ -14,7 +14,6 @@ function main() {
   markdown.push('| Rule ID | Rule Name(s) | Description | Severity | Tags |')
   markdown.push('| ------- | ------------ | ----------- | -------- | ---- |')
 
-  // Collect all rules and their generated rows
   const mdRules: Array<{ ruleId: string; row: string }> = []
   const ghRules: Array<{ ruleId: string; row: string }> = []
   const ghdRules: Array<{ ruleId: string; row: string }> = []
@@ -35,7 +34,6 @@ function main() {
     row.push(allConfig[ruleName].severity)
     row.push(rule.tags.join(', '))
 
-    // Categorize rules by their ID prefix
     const ruleData = { ruleId: rule.names[0], row: `| ${row.join(' | ')} |` }
     if (rule.names[0].startsWith('GHD')) {
       ghdRules.push(ruleData)
@@ -46,7 +44,6 @@ function main() {
     }
   }
 
-  // Sort each category alphabetically by rule ID
   mdRules.sort((a, b) => a.ruleId.localeCompare(b.ruleId))
   ghRules.sort((a, b) => a.ruleId.localeCompare(b.ruleId))
   ghdRules.sort((a, b) => a.ruleId.localeCompare(b.ruleId))
@@ -66,13 +63,12 @@ function main() {
   writeFileSync('data/reusables/contributing/content-linter-rules.md', markdown.join('\n'))
 }
 
-// The search-replace rule configures multiple psuedo-rules
+// The search-replace rule configures multiple pseudo-rules
 // under the rules key.
 function getSearchReplaceRules(srRule: Rule, ruleConfig: Config) {
   const name = srRule.information ? `[search-replace](${srRule.information})` : 'search-replace'
   const markdown = []
 
-  // Sort rules alphabetically by name
   const sortedRules = [...(ruleConfig.rules || [])].sort((a, b) => a.name.localeCompare(b.name))
 
   for (const rule of sortedRules) {
diff --git a/src/content-linter/scripts/lint-content.ts b/src/content-linter/scripts/lint-content.ts
index 416c33b37b78..b58caf6b09bb 100755
--- a/src/content-linter/scripts/lint-content.ts
+++ b/src/content-linter/scripts/lint-content.ts
@@ -26,7 +26,6 @@ import type {
 } from 'markdownlint'
 import type { Rule, Config } from '@/content-linter/types'
 
-// Type definitions for Markdownlint results
 interface LintError {
   lineNumber: number
   ruleNames: string[]
@@ -88,11 +87,8 @@ interface FormattedResult {
 
 type FormattedResults = Record<string, FormattedResult[]>
 
-/**
- * Config that applies to all rules in all environments (CI, reports, precommit).
- */
+// Config that applies to all rules in all environments (CI, reports, precommit).
 export const globalConfig = {
-  // Do not ever lint these filepaths
   excludePaths: ['content/contributing/', 'data/llms-txt/'],
 }
 
@@ -150,7 +146,8 @@ async function main() {
   // Get the updated paths after validation (invalid paths will have been filtered out)
   const validatedPaths = program.opts().paths
 
-  // If paths has not been specified, lint all files
+  // With no paths and no --summary-by-rule, fall back to the files changed
+  // in the local git checkout.
   const files = getFilesToLint(
     (summaryByRule && ALL_CONTENT_DIR) || validatedPaths || getChangedFiles(),
   )
@@ -169,7 +166,6 @@ async function main() {
   spinner.start()
   const start = Date.now()
 
-  // Initializes the config to pass to markdownlint based on the input options
   const { config, configuredRules } = getMarkdownLintConfig(errorsOnly, rules)
 
   // Run Markdownlint for content directory
@@ -395,9 +391,8 @@ function getFilesToLint(inputPaths: string[]): FileList {
   const root = path.resolve(languages.en.dir)
   const contentDir = path.join(root, 'content')
   const dataDir = path.join(root, 'data')
-  // The path passed to Markdownlint is what is displayed
-  // in the error report, so we want to normalize it and
-  // and make it relative if it's absolute.
+  // The path passed to Markdownlint is what is displayed in the error report,
+  // so normalize it and make it relative if it's absolute.
   for (const rawPath of inputPaths) {
     const absPath = path.resolve(rawPath)
     if (fs.statSync(rawPath).isDirectory()) {
@@ -418,7 +413,7 @@ function getFilesToLint(inputPaths: string[]): FileList {
         }
       }
       // If it's a file but it's not part of the content or the data
-      // directory, it's probably file passed in by computing changed files
+      // directory, it's probably a file passed in by computing changed files
       // from the git diff.
     }
   }
@@ -436,7 +431,6 @@ function getFilesToLint(inputPaths: string[]): FileList {
 
       const relPath = path.relative(root, filePath)
 
-      // Skip files that match any of the excluded paths
       if (globalConfig.excludePaths.some((excludePath) => relPath.startsWith(excludePath))) {
         continue
       }
@@ -452,7 +446,6 @@ function getFilesToLint(inputPaths: string[]): FileList {
   fileList.data = cleanPaths(fileList.data)
   fileList.yml = cleanPaths(fileList.yml)
 
-  // Add a total fileList length property
   fileList.length = fileList.content.length + fileList.data.length + fileList.yml.length
 
   return fileList
@@ -504,11 +497,9 @@ function reportSummaryByRule(results: LintResults, config: LintConfig): void {
   }
 }
 
-/*
-  Filter out the files with one or more results and format each
-  result. Results are sorted by severity per file, with errors
-  listed first then warnings.
-*/
+// Filter out the files with one or more results and format each result.
+// Results are sorted by severity per file, with errors listed first then
+// warnings.
 function getFormattedResults(
   allResults: LintResults,
   isInPrecommitMode: boolean,
@@ -527,7 +518,6 @@ function getFormattedResults(
         .map((flaw: LintError) => formatResult(flaw, isInPrecommitMode))
         .filter((result): result is FormattedResult => result !== null)
 
-      // Only add the file to output if there are results after filtering
       if (formattedResults.length > 0) {
         const errors = formattedResults.filter((result) => result.severity === 'error')
         const warnings = formattedResults.filter((result) => result.severity === 'warning')
@@ -539,17 +529,10 @@ function getFormattedResults(
   return output
 }
 
-// Results are formatted with the key being the filepath
-// and the value being an array of errors for that filepath.
-// Each result has a rule name, which when looked up in `allConfig`
-// will give us its severity and we filter those that are 'warning'.
 function getWarningCountByFile(results: FormattedResults, fixed = false): number {
   return getCountBySeverity(results, 'warning', fixed)
 }
 
-// Results are formatted with the key being the filepath
-// and the value being an array of results for that filepath.
-// Each result in the array has a severity of error or warning.
 function getErrorCountByFile(results: FormattedResults, fixed = false): number {
   return getCountBySeverity(results, 'error', fixed)
 }
@@ -574,7 +557,6 @@ function getCountBySeverity(
 function formatResult(object: LintError, isInPrecommitMode: boolean): FormattedResult | null {
   const formattedResult: FormattedResult = {} as FormattedResult
 
-  // Add severity to each result object
   const ruleName = object.ruleNames[1] || object.ruleNames[0]
   const ruleConfig = allConfig[ruleName] as Config | undefined
   // Skip rules that aren't in our config. This can happen when using
@@ -632,13 +614,9 @@ function listRules() {
   return ruleList
 }
 
-/*
-  Based on input options, configure the Markdownlint rules to run
-  There are a subset of rules that can't be run on data files, since
-  those Markdown files are partials included in full Markdown files.
-  Rules that can't be run on partials have the property
-  `partial-markdown-files` set to false.
-*/
+// Some rules can't be run on data files, since those Markdown files are
+// partials included in full Markdown files. Those rules have the property
+// `partial-markdown-files` set to false.
 function getMarkdownLintConfig(
   filterErrorsOnly: boolean,
   runRules: string[] | undefined,
@@ -670,7 +648,6 @@ function getMarkdownLintConfig(
       continue
     }
 
-    // Check if the rule should be included based on user-specified rules
     if (runRules && !shouldIncludeRule(ruleName, runRules)) continue
 
     // There are a subset of rules run on just the frontmatter in files
@@ -678,9 +655,6 @@ function getMarkdownLintConfig(
       config.frontMatter[ruleName] = ruleConfig
       if (customRule) configuredRules.frontMatter.push(customRule)
     }
-    // Handle the special case of the search-replace rule
-    // which has nested rules each with their own
-    // severity and metadata.
     if (ruleName === 'search-replace') {
       const searchReplaceRules: NonNullable<Config['rules']> = []
       const dataSearchReplaceRules: NonNullable<Config['rules']> = []
@@ -691,14 +665,12 @@ function getMarkdownLintConfig(
       for (const searchRule of ruleConfig.rules) {
         const searchRuleSeverity = getSeverity(searchRule, isPrecommit)
         if (filterErrorsOnly && searchRuleSeverity !== 'error') continue
-        // Add search-replace rules to frontmatter configuration for rules that make sense in frontmatter
-        // This ensures rules like TODOCS detection work in frontmatter
-        // Rules with applyToFrontmatter should ONLY run in the frontmatter pass (which lints the entire file)
-        // to avoid duplicate detections
+        // The frontmatter pass lints the whole file, so a rule with
+        // applyToFrontmatter must run there and nowhere else, or every match
+        // gets reported twice.
         if (searchRule.applyToFrontmatter) {
           frontmatterSearchReplaceRules.push(searchRule)
         } else {
-          // Only add to content rules if not a frontmatter-specific rule
           searchReplaceRules.push(searchRule)
         }
         if (searchRule['partial-markdown-files']) {
@@ -765,7 +737,6 @@ function getCustomRule(ruleName: string): Rule | MarkdownlintRule {
 // Check if a rule should be included based on user-specified rules
 // Handles both short names (e.g., GHD047, MD001) and long names (e.g., table-column-integrity, heading-increment)
 export function shouldIncludeRule(ruleName: string, runRules: string[]) {
-  // First check if the rule name itself is in the list
   if (runRules.includes(ruleName)) {
     return true
   }
@@ -789,7 +760,7 @@ export function shouldIncludeRule(ruleName: string, runRules: string[]) {
   The severity of the search-replace custom rule is embedded in
   each individual search rule. This function returns the severity
   of the individual search rule. The name we define for each search
-  rule shows up the the errorDetail property of the error object.
+  rule shows up in the errorDetail property of the error object.
   The error object returned from Markdownlint has the following structure:
 
   {
@@ -830,11 +801,10 @@ function isOptionsValid() {
       } else {
         console.warn(`warning: the value '${filePath}' was not found. Skipping this path.`)
       }
-      // Continue processing - don't return false here
+      // Keep going: one bad path should not abandon the rest.
     }
   }
 
-  // Update the program options to only include valid paths
   if (optionPaths.length > 0) {
     program.setOptionValue('paths', validPaths)
   }
diff --git a/src/content-linter/scripts/lint-report.ts b/src/content-linter/scripts/lint-report.ts
index 7e39cc15fd9c..f77bde4d3df0 100644
--- a/src/content-linter/scripts/lint-report.ts
+++ b/src/content-linter/scripts/lint-report.ts
@@ -13,11 +13,8 @@ const MAX_ISSUE_BODY_SIZE = 60000
 // If the number of warnings exceeds this number, print a warning so we can give them attention
 const MAX_WARNINGS_BEFORE_ALERT = 20
 
-/**
- * Config that only applies to automated weekly reports.
- */
+// Config that only applies to automated weekly reports.
 export const reportingConfig = {
-  // Include only rules with these severities in reports
   includeSeverities: ['error', 'warning'],
   // Include these rules regardless of severity in reports
   includeRules: ['expired-content'],
@@ -29,13 +26,9 @@ interface LintFlaw {
   errorDetail?: string
 }
 
-/**
- * Determines if a lint result should be included in the automated report
- */
 function shouldIncludeInReport(flaw: LintFlaw): boolean {
   const allRuleNames = getAllRuleNames(flaw)
 
-  // Check if severity should be included
   if (reportingConfig.includeSeverities.includes(flaw.severity)) {
     return true
   }
@@ -95,12 +88,10 @@ async function main() {
   // Keep track of warnings so we can print an alert when they exceed a manageable number
   let totalWarnings = 0
 
-  // Filter results based on reporting configuration
   const filteredResults: Record<string, LintFlaw[]> = {}
   for (const [file, flaws] of Object.entries(parsedResults)) {
     const filteredFlaws = (flaws as LintFlaw[]).filter((flaw) => shouldIncludeInReport(flaw))
 
-    // Only include files that have remaining flaws after filtering
     if (filteredFlaws.length > 0) {
       totalWarnings += filteredFlaws.filter((flaw) => flaw.severity === 'warning').length
       filteredResults[file] = filteredFlaws
@@ -119,7 +110,6 @@ async function main() {
   for (const [file, flaws] of Object.entries(filteredResults)) {
     const fileEntry = `File: \`${file}\`:\n\`\`\`json\n${JSON.stringify(flaws, null, 2)}\n\`\`\`\n`
 
-    // Check if adding this file would exceed the size limit
     if (reportBody.length + fileEntry.length > MAX_ISSUE_BODY_SIZE) {
       truncated = true
       break
@@ -129,7 +119,6 @@ async function main() {
     filesIncluded++
   }
 
-  // Add truncation notice if needed
   if (truncated) {
     const remaining = totalFiles - filesIncluded
     reportBody += `\n---\n\n⚠️ **Output truncated**: Showing ${filesIncluded} of ${totalFiles} files with lint issues. ${remaining} additional files have been omitted to stay within GitHub's issue size limits.\n`
diff --git a/src/content-linter/scripts/pretty-print-results.ts b/src/content-linter/scripts/pretty-print-results.ts
index bd758d0d949f..1bc20181b91f 100644
--- a/src/content-linter/scripts/pretty-print-results.ts
+++ b/src/content-linter/scripts/pretty-print-results.ts
@@ -37,9 +37,9 @@ export function prettyPrintResults(
 
   for (const [file, flaws] of Object.entries(results)) {
     console.log(chalk.bold(file))
-    console.log('') // blank line
+    console.log('')
 
-    // It's very possible that a the same file has multiple flaws of the
+    // It's very possible that the same file has multiple flaws of the
     // same rule but on different line numbers.
     const sorted = [...flaws]
       .sort((a, b) => a.lineNumber - b.lineNumber)
diff --git a/src/content-linter/tests/category-pages.ts b/src/content-linter/tests/category-pages.ts
index 2c31c6ef04ca..e12311db0328 100644
--- a/src/content-linter/tests/category-pages.ts
+++ b/src/content-linter/tests/category-pages.ts
@@ -66,13 +66,12 @@ describe.skip('category pages', () => {
       // Only include category directories, not standalone category files like content/actions/quickstart.md
       .filter((link) => fs.existsSync(getPath(productDir, link, 'index')))
 
-    // Map those to the Markdown file paths that represent that category page index
     const categoryPaths = categoryLinks.map((link) => getPath(productDir, link, 'index'))
 
     // Make them relative for nicer display in test names
     const categoryRelativePaths = categoryPaths.map((p) => path.relative(contentDir, p))
 
-    // Combine those to fit vitests's `.each` usage
+    // Combine those to fit vitest's `.each` usage
     const categoryTuples = zip(categoryRelativePaths, categoryPaths, categoryLinks) as [
       string,
       string,
@@ -121,7 +120,6 @@ describe.skip('category pages', () => {
           await contextualize(req as ExtendedRequest, res as Response, next)
           await shortVersions(req as ExtendedRequest, res as Response, next)
 
-          // Read the product index data for rendering
           const productIndexContents = await fs.promises.readFile(productIndex, 'utf8')
           const productIndexData = getFrontmatterData(productIndexContents)
 
@@ -145,7 +143,7 @@ describe.skip('category pages', () => {
                 const articleContents = await fs.promises.readFile(articlePath, 'utf8')
                 const articleData = getFrontmatterData(articleContents)
 
-                // Do not include subcategories in list of published articles
+                // Do not include subcategories nor hidden pages in list of published articles
                 if (articleData.subcategory || articleData.hidden) return null
 
                 // ".../content/github/{category}/{article}.md" => "/{article}"
@@ -154,7 +152,6 @@ describe.skip('category pages', () => {
             )
           ).filter(Boolean) as string[]
 
-          // Get all of the child articles that exist in the subdir
           const childEntries = await fs.promises.readdir(categoryDir, { withFileTypes: true })
           const childFileEntries = childEntries.filter(
             (ent) => ent.isFile() && ent.name !== 'index.md',
@@ -212,7 +209,6 @@ describe.skip('category pages', () => {
         test('slugified title matches parent directory name', () => {
           if (allowTitleToDifferFromFilename) return
 
-          // Get the parent directory name
           const categoryDirPath = path.dirname(indexAbsPath)
           const categoryDirName = path.basename(categoryDirPath)
 
@@ -230,7 +226,6 @@ describe.skip('category pages', () => {
           const expectedSlug = expectedSlugs.at(-1) as string
           const newCategoryDirPath = path.join(path.dirname(categoryDirPath), expectedSlug)
           customMessage += `\nTo resolve this consider running:\n  ./src/content-render/scripts/move-content.ts ${categoryDirPath} ${newCategoryDirPath}\n`
-          // Check if the directory name matches the expected slug
           expect(expectedSlugs.includes(categoryDirName), customMessage).toBeTruthy()
         })
       },
diff --git a/src/content-linter/tests/integration/lint-cli.ts b/src/content-linter/tests/integration/lint-cli.ts
index c089f08df799..bbc7a701c9c5 100644
--- a/src/content-linter/tests/integration/lint-cli.ts
+++ b/src/content-linter/tests/integration/lint-cli.ts
@@ -1,24 +1,9 @@
-/**
- * Integration tests for the content linter CLI script.
- *
- * These tests verify the actual end-to-end behavior of the lint-content script
- * by running it via npm commands and checking the output. Unlike unit tests that
- * test individual functions in isolation, these tests catch issues in the full
- * CLI workflow including:
- *
- * - Command-line argument parsing
- * - File discovery and processing logic
- * - Rule configuration and filtering
- * - Error reporting and exit codes
- *
- * Test file structure:
- * - Test files are created in content/test-integration/ during tests
- * - This ensures the linter actually processes them (it only processes files in content/ or data/)
- * - Files are cleaned up after each test
- *
- * These tests serve as regression protection and verify that the linter
- * continues to work as expected when changes are made to the CLI logic.
- */
+// End-to-end tests for the lint-content script, run via npm and checked by
+// their output. They cover argument parsing, file discovery, rule filtering,
+// and exit codes.
+//
+// Test files are written to content/test-integration/ because the linter only
+// processes files under content/ or data/.
 
 import { execSync } from 'child_process'
 import { beforeEach, afterEach, describe, test, expect } from 'vitest'
@@ -29,18 +14,14 @@ const rootDir = path.join(__dirname, '../../../..')
 const testContentDir = path.join(rootDir, 'content/test-integration')
 
 describe('Content Linter CLI Integration Tests', { timeout: 30000 }, () => {
-  // Run all tests in sequence to avoid npm process conflicts
   beforeEach(async () => {
-    // Create test directory
     await fs.mkdir(testContentDir, { recursive: true })
   })
 
   afterEach(async () => {
-    // Clean up test files
     await fs.rm(testContentDir, { recursive: true, force: true })
   })
 
-  // Helper function to run linter commands
   async function runLinter(args: string): Promise<{ output: string; exitCode: number }> {
     let output = ''
     let exitCode = 0
@@ -50,7 +31,7 @@ describe('Content Linter CLI Integration Tests', { timeout: 30000 }, () => {
         encoding: 'utf8',
         cwd: rootDir,
         stdio: 'pipe',
-        timeout: 10000, // 10 second timeout
+        timeout: 10000,
       })
     } catch (error: unknown) {
       const execError = error as { stdout?: string; stderr?: string; status?: number }
@@ -63,7 +44,7 @@ describe('Content Linter CLI Integration Tests', { timeout: 30000 }, () => {
 
   describe('Linter functionality verification', () => {
     test('should detect errors when explicitly running search-replace rule', async () => {
-      // Baseline test - ensures the linter can detect errors
+      // Baseline: if this fails, the linter is not detecting anything at all.
       const testFile = path.join(testContentDir, 'baseline-test.md')
       const testContent = `---
 title: Baseline Test
@@ -110,10 +91,9 @@ TODOCS This is placeholder content that should now be detected by default.
 
       const { output, exitCode } = await runLinter(`--paths "${testFile}"`)
 
-      // Verify that the linter properly detects errors when no --rules are specified
-      expect(exitCode).toBe(1) // Should exit with error due to TODOCS
-      expect(output).toContain('todocs-placeholder') // TODOCS should be detected by default
-      expect(output).toContain('ERROR') // Errors should be detected
+      expect(exitCode).toBe(1)
+      expect(output).toContain('todocs-placeholder')
+      expect(output).toContain('ERROR')
     })
 
     test('should respect rule filtering when specific rules are provided', async () => {
@@ -137,7 +117,7 @@ TODOCS This file has multiple error types.
         `--paths "${testFile}" --rules heading-increment`,
       )
 
-      expect(exitCode).toBe(0) // heading-increment rule behavior with filtering
+      expect(exitCode).toBe(0)
       expect(output).not.toContain('ERROR')
       expect(output).not.toContain('todocs-placeholder')
     })
diff --git a/src/content-linter/tests/lint-files.ts b/src/content-linter/tests/lint-files.ts
index 1cd3f18a2a0a..dd6a6f916721 100755
--- a/src/content-linter/tests/lint-files.ts
+++ b/src/content-linter/tests/lint-files.ts
@@ -166,7 +166,6 @@ const yamlWalkOptions = {
   includeBasePath: true,
 }
 
-// different lint rules apply to different content types
 let ymlToLint
 
 // compile lists of all the files we want to lint
@@ -199,7 +198,6 @@ function formatLinkError(message: string, links: string[]) {
 
 // Returns `content` if its a string, or `content.description` if it can.
 // Used for getting the nested `description` key in glossary files.
-// Using any because content can be string | { description: string } | other YAML structures
 function getContent(content: unknown) {
   if (typeof content === 'string') return content
   if (
@@ -214,7 +212,7 @@ function getContent(content: unknown) {
 
 const diffFiles = getDiffFiles()
 
-// If present, and not empty, leverage it because in most cases it's empty.
+// If it is present and not empty, use it. In most cases it is empty.
 if (diffFiles.length > 0) {
   // It's faster to do this once and then re-use over and over in the
   // .filter() later on.
diff --git a/src/content-linter/tests/site-data-references.ts b/src/content-linter/tests/site-data-references.ts
index c980541b8fc0..c0828043b187 100644
--- a/src/content-linter/tests/site-data-references.ts
+++ b/src/content-linter/tests/site-data-references.ts
@@ -33,7 +33,7 @@ describe('data references', () => {
   vi.setConfig({ testTimeout: 60 * 1000 })
 
   test('every data reference found in English variable files is defined and has a value', async () => {
-    // value can be any type returned by getDataByLanguage - we check if it's a string
+    // getDataByLanguage can return any YAML type, so the string check happens below.
     let errors: Array<{ key: string; value: unknown; variableFile: string }> = []
     const allVariables = getDeepDataByLanguage('variables', 'en')
     const variables = Object.values(allVariables)
@@ -54,7 +54,7 @@ describe('data references', () => {
       }),
     )
 
-    errors = uniqWith(errors, isEqual) // remove duplicates
+    errors = uniqWith(errors, isEqual)
     expect(errors.length, JSON.stringify(errors, null, 2)).toBe(0)
   })
 })
diff --git a/src/content-linter/tests/unit/ctas-schema.ts b/src/content-linter/tests/unit/ctas-schema.ts
index 0712e6541857..9fa8139057b7 100644
--- a/src/content-linter/tests/unit/ctas-schema.ts
+++ b/src/content-linter/tests/unit/ctas-schema.ts
@@ -82,11 +82,11 @@ try_ghec_for_free: '{% ifversion ghec %}https://github.com/account/enterprises/n
     expect(errors.length).toBe(1) // Should detect and try to convert the old CTA format
     expect(errors[0].fixInfo).toBeDefined()
 
-    // The extracted URL should not include the curly brace - verify by checking the fix
+    // The extracted URL should not include the curly brace from the Liquid tag.
     const fixedUrl = errors[0].fixInfo?.insertText
     expect(fixedUrl).toBeDefined()
-    expect(fixedUrl).not.toContain('{') // Should not include curly brace from Liquid syntax
-    expect(fixedUrl).not.toContain('}') // Should not include curly brace from Liquid syntax
+    expect(fixedUrl).not.toContain('{')
+    expect(fixedUrl).not.toContain('}')
     expect(fixedUrl).toContain('ref_product=ghec') // Should have converted old format correctly
   })
 
diff --git a/src/content-linter/tests/unit/frontmatter-content-type.ts b/src/content-linter/tests/unit/frontmatter-content-type.ts
index 932e88902f6e..84e5a5ed83e3 100644
--- a/src/content-linter/tests/unit/frontmatter-content-type.ts
+++ b/src/content-linter/tests/unit/frontmatter-content-type.ts
@@ -38,9 +38,7 @@ describe('GHD065 - frontmatter-content-type', () => {
     resetCache()
   })
 
-  // -------------------------------------------------------------------
   // Passing cases
-  // -------------------------------------------------------------------
 
   test('file with correct contentType matching directory passes', async () => {
     const strings = {
@@ -101,7 +99,7 @@ describe('GHD065 - frontmatter-content-type', () => {
 
   test('file outside qualifying product is not checked', async () => {
     // actions in fixtures has non-EDI subdirs (category/, using-workflows/),
-    // so it does NOT qualify — the rule should skip it entirely.
+    // so it does NOT qualify and the rule should skip it entirely.
     const strings = {
       'content/actions/category/test-file.md': md(['title: Test', 'versions:', "  fpt: '*'"]),
     }
@@ -119,9 +117,7 @@ describe('GHD065 - frontmatter-content-type', () => {
     expect(errors).toEqual([])
   })
 
-  // -------------------------------------------------------------------
   // Failing cases
-  // -------------------------------------------------------------------
 
   test('missing contentType in qualifying product triggers error', async () => {
     const strings = {
diff --git a/src/content-linter/tests/unit/frontmatter-landing-carousels.ts b/src/content-linter/tests/unit/frontmatter-landing-carousels.ts
index 3238d9555f7e..2aaeeefd3f63 100644
--- a/src/content-linter/tests/unit/frontmatter-landing-carousels.ts
+++ b/src/content-linter/tests/unit/frontmatter-landing-carousels.ts
@@ -92,14 +92,9 @@ describe(ruleName, () => {
   })
 
   test('absolute paths are prioritized over relative paths', async () => {
-    // This test verifies that when both absolute and relative paths exist with the same name,
-    // the absolute path is chosen over the relative path.
-    //
-    // Setup:
-    // - /article-one should resolve to src/fixtures/fixtures/content/article-one.md (absolute)
-    // - article-one (relative) would resolve to src/content-linter/tests/fixtures/landing-carousels/article-one.md
-    //
-    // The test passes because our logic prioritizes the absolute path resolution first
+    // /article-one exists both as src/fixtures/fixtures/content/article-one.md
+    // and as src/content-linter/tests/fixtures/landing-carousels/article-one.md.
+    // The absolute resolution wins.
     const result = await runRule(frontmatterLandingCarousels, {
       files: [ABSOLUTE_PRIORITY],
       ...fmOptions,
@@ -108,16 +103,7 @@ describe(ruleName, () => {
   })
 
   test('path priority resolution works correctly', async () => {
-    // This test verifies that absolute paths are prioritized over relative paths
-    // when both files exist with the same name.
-    //
-    // Setup:
-    // - /article-one could resolve to EITHER:
-    //   1. src/fixtures/fixtures/content/article-one.md (absolute - should be chosen)
-    //   2. src/content-linter/tests/fixtures/landing-carousels/article-one.md (relative - should be ignored)
-    //
-    // Our prioritization logic should choose #1 (absolute) over #2 (relative)
-    // This test passes because the absolute path exists and is found first
+    // Same collision as the test above, reached through a different fixture.
     const result = await runRule(frontmatterLandingCarousels, {
       files: [PATH_PRIORITY],
       ...fmOptions,
@@ -126,10 +112,7 @@ describe(ruleName, () => {
   })
 
   test('absolute-only paths work when no relative path exists', async () => {
-    // This test verifies that absolute path resolution works when no relative path exists
-    // /article-two exists in src/fixtures/fixtures/content/article-two.md
-    // but NOT in src/content-linter/tests/fixtures/landing-carousels/article-two.md
-    // This test would fail if we didn't prioritize absolute paths properly
+    // /article-two resolves from src/fixtures/fixtures/content/article-two.md.
     const result = await runRule(frontmatterLandingCarousels, {
       files: [ABSOLUTE_ONLY],
       ...fmOptions,
diff --git a/src/content-linter/tests/unit/frontmatter-schema.ts b/src/content-linter/tests/unit/frontmatter-schema.ts
index a4ca19a5c20b..8fa299079eb2 100644
--- a/src/content-linter/tests/unit/frontmatter-schema.ts
+++ b/src/content-linter/tests/unit/frontmatter-schema.ts
@@ -3,7 +3,7 @@ import { describe, expect, test } from 'vitest'
 import { runRule } from '../../lib/init-test'
 import { frontmatterSchema } from '../../lib/linting-rules/frontmatter-schema'
 
-// Configure the test figure to not split frontmatter and content
+// Configure the test fixture to not split frontmatter and content
 const fmOptions = { markdownlintOptions: { frontMatter: null } }
 
 describe(frontmatterSchema.names.join(' - '), () => {
diff --git a/src/content-linter/tests/unit/frontmatter-search-replace.ts b/src/content-linter/tests/unit/frontmatter-search-replace.ts
index 152e61e67290..788f41102dbf 100644
--- a/src/content-linter/tests/unit/frontmatter-search-replace.ts
+++ b/src/content-linter/tests/unit/frontmatter-search-replace.ts
@@ -19,7 +19,6 @@ describe('search-replace rule in frontmatter', () => {
 
     const errors = result.markdown || []
 
-    // Should find TODOCS in frontmatter
     const todosErrors = errors.filter((e) => e.errorDetail && /TODOCS/.test(e.errorDetail))
     expect(todosErrors.length).toBe(1)
     expect(todosErrors[0].lineNumber).toBe(2) // title: TODOCS
@@ -47,7 +46,6 @@ describe('search-replace rule in frontmatter', () => {
 
     const errors = result.markdown || []
 
-    // Should find all TODOCS instances in frontmatter
     const todosErrors = errors.filter((e) => e.errorDetail && /TODOCS/.test(e.errorDetail))
     expect(todosErrors.length).toBe(3)
     expect(todosErrors[0].lineNumber).toBe(2) // title: TODOCS
@@ -77,7 +75,6 @@ describe('search-replace rule in frontmatter', () => {
 
     const errors = result.markdown || []
 
-    // Should find domain errors in frontmatter
     const domainErrors = errors.filter(
       (e) => e.errorDetail && /docs-domain|help-domain|developer-domain/.test(e.errorDetail),
     )
@@ -108,7 +105,6 @@ describe('search-replace rule in frontmatter', () => {
 
     const errors = result.markdown || []
 
-    // Should find deprecated syntax errors in frontmatter
     const deprecatedErrors = errors.filter(
       (e) => e.errorDetail && /site\.data|octicon/.test(e.errorDetail),
     )
diff --git a/src/content-linter/tests/unit/frontmatter-versions-whitespace.ts b/src/content-linter/tests/unit/frontmatter-versions-whitespace.ts
index 99ca3a013552..d81bf4350f8d 100644
--- a/src/content-linter/tests/unit/frontmatter-versions-whitespace.ts
+++ b/src/content-linter/tests/unit/frontmatter-versions-whitespace.ts
@@ -18,7 +18,6 @@ interface InvalidTestCase {
   expectedMessage?: string
 }
 
-// Valid cases - should pass
 const validCases: ValidTestCase[] = [
   {
     name: 'valid-simple-versions',
@@ -63,7 +62,6 @@ This is a test.
   },
 ]
 
-// Invalid cases - should fail
 const invalidCases: InvalidTestCase[] = [
   {
     name: 'trailing-whitespace',
diff --git a/src/content-linter/tests/unit/image-alt-text-end-punctuation.ts b/src/content-linter/tests/unit/image-alt-text-end-punctuation.ts
index c4e05da23279..956692c95240 100644
--- a/src/content-linter/tests/unit/image-alt-text-end-punctuation.ts
+++ b/src/content-linter/tests/unit/image-alt-text-end-punctuation.ts
@@ -59,9 +59,8 @@ describe(imageAltTextEndPunctuation.names.join(' - '), () => {
     ].join('\n')
     const result = await runRule(imageAltTextEndPunctuation, { strings: { markdown } })
     const errors = result.markdown
-    // This rule is not concerned with empty alt text
-    // That will be caught by the incorrect-alt-text-length rule
-    // So technically, it's not imageAltTextEndPunctuation's problem.
+    // This rule is not concerned with empty alt text. The
+    // incorrect-alt-text-length rule catches that instead.
     expect(errors.length).toBe(0)
   })
 })
diff --git a/src/content-linter/tests/unit/image-alt-text-exclude-start-words.ts b/src/content-linter/tests/unit/image-alt-text-exclude-start-words.ts
index 7b2bdac0f7b1..885c7f470e80 100644
--- a/src/content-linter/tests/unit/image-alt-text-exclude-start-words.ts
+++ b/src/content-linter/tests/unit/image-alt-text-exclude-start-words.ts
@@ -39,9 +39,8 @@ describe(imageAltTextExcludeStartWords.names.join(' - '), () => {
     ].join('\n')
     const result = await runRule(imageAltTextExcludeStartWords, { strings: { markdown } })
     const errors = result.markdown
-    // This rule is not concerned with empty alt text
-    // That will be caught by the incorrect-alt-text-empty rule
-    // So technically, it's not imageAltTextEndPunctuation's problem.
+    // This rule is not concerned with empty alt text. The
+    // incorrect-alt-text-length rule catches that instead.
     expect(errors.length).toBe(0)
   })
 })
diff --git a/src/content-linter/tests/unit/internal-links-no-lang.ts b/src/content-linter/tests/unit/internal-links-no-lang.ts
index e883adf5a55c..66d8eaf970bb 100644
--- a/src/content-linter/tests/unit/internal-links-no-lang.ts
+++ b/src/content-linter/tests/unit/internal-links-no-lang.ts
@@ -29,7 +29,7 @@ describe(internalLinksNoLang.names.join(' - '), () => {
       // a // means the link is external
       'These are the [Docs](//ja/actions) we need.',
       'This is the [actions Docs](/actions)',
-      // A link that starts with a language code
+      // Starts with a path segment that is not a language code
       '[Enterprise](/enterprise/overview)',
     ].join('\n')
     const result = await runRule(internalLinksNoLang as Rule, { strings: { markdown } })
diff --git a/src/content-linter/tests/unit/internal-links-old-version.ts b/src/content-linter/tests/unit/internal-links-old-version.ts
index 84c0510dd77e..39e4e4590de6 100644
--- a/src/content-linter/tests/unit/internal-links-old-version.ts
+++ b/src/content-linter/tests/unit/internal-links-old-version.ts
@@ -24,7 +24,7 @@ describe(internalLinksOldVersion.names.join(' - '), () => {
     const markdown = [
       // External links with enterprise in them
       '[External link](https://someservice.com/enterprise/1.0/admin/yes)',
-      // Current versioning links is excluded from this test
+      // Current versioning links are excluded from this test
       '[New versioning](/github/site-policy/enterprise/2.2/yes)',
     ].join('\n')
     const result = await runRule(internalLinksOldVersion as Rule, { strings: { markdown } })
diff --git a/src/content-linter/tests/unit/lint-report-exclusions.ts b/src/content-linter/tests/unit/lint-report-exclusions.ts
index 7879f14a3987..e9fe1bd8c6d3 100644
--- a/src/content-linter/tests/unit/lint-report-exclusions.ts
+++ b/src/content-linter/tests/unit/lint-report-exclusions.ts
@@ -51,7 +51,6 @@ describe('content linter configuration', () => {
     function shouldIncludeInReport(flaw: LintFlaw): boolean {
       const allRuleNames = getAllRuleNames(flaw)
 
-      // Check if severity should be included
       if (reportingConfig.includeSeverities.includes(flaw.severity)) {
         return true
       }
diff --git a/src/content-linter/tests/unit/liquid-ifversion-versions.ts b/src/content-linter/tests/unit/liquid-ifversion-versions.ts
index 9b602487cda2..7a3c831d3b8d 100644
--- a/src/content-linter/tests/unit/liquid-ifversion-versions.ts
+++ b/src/content-linter/tests/unit/liquid-ifversion-versions.ts
@@ -114,8 +114,7 @@ describe(liquidIfversionVersions.names.join(' - '), () => {
   })
 
   test.skip('ifversion using feature based version extended with shortname all versions', async () => {
-    // That `features/volvo.yml` contains `fpt:'*', ghec:'*'`
-    // so combined with the
+    // That `features/volvo.yml` contains `fpt:'*', ghec:'*'`.
     const markdown = `
       {% ifversion volvo or ghes %}{% endif %}
     `
diff --git a/src/content-linter/tests/unit/liquid-syntax.ts b/src/content-linter/tests/unit/liquid-syntax.ts
index 2cc769ce9bbd..a503b869def0 100644
--- a/src/content-linter/tests/unit/liquid-syntax.ts
+++ b/src/content-linter/tests/unit/liquid-syntax.ts
@@ -3,7 +3,7 @@ import { describe, expect, test } from 'vitest'
 import { runRule } from '../../lib/init-test'
 import { frontmatterLiquidSyntax, liquidSyntax } from '../../lib/linting-rules/liquid-syntax'
 
-// Configure the test figure to not split frontmatter and content
+// Configure the test fixture to not split frontmatter and content
 const fmOptions = { markdownlintOptions: { frontMatter: null } }
 
 describe(frontmatterLiquidSyntax.names.join(' - '), () => {
diff --git a/src/content-linter/tests/unit/liquid-versioning.ts b/src/content-linter/tests/unit/liquid-versioning.ts
index 2711ce83ee9e..0d142a66b43d 100644
--- a/src/content-linter/tests/unit/liquid-versioning.ts
+++ b/src/content-linter/tests/unit/liquid-versioning.ts
@@ -58,7 +58,7 @@ describe(liquidIfVersionTags.names.join(' - '), () => {
       '{% ifversion ghes < 2.9 %}',
       // Incorrect syntax
       '{% ifversion ghec or ifversion fpt %}',
-      // Typo - should be not ghec
+      // Typo: should be `not ghec`
       '{% ifversion no ghec %}',
     ]
     const result = await runRule(liquidIfVersionTags, {
diff --git a/src/content-linter/tests/unit/rai-app-card-structure.ts b/src/content-linter/tests/unit/rai-app-card-structure.ts
index 82394e1ad94c..ef1f838dacc1 100644
--- a/src/content-linter/tests/unit/rai-app-card-structure.ts
+++ b/src/content-linter/tests/unit/rai-app-card-structure.ts
@@ -3,11 +3,7 @@ import { describe, expect, test } from 'vitest'
 import { runRule } from '../../lib/init-test'
 import { raiAppCardStructure } from '../../lib/linting-rules/rai-app-card-structure'
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** A minimal valid RAI card with all required H2s, H3s, and reusables. */
+// A minimal valid RAI card with all required H2s, H3s, and reusables.
 function validCard(): string {
   return [
     '---',
@@ -102,9 +98,7 @@ function validCard(): string {
 }
 
 describe(raiAppCardStructure.names.join(' - '), () => {
-  // -----------------------------------------------------------------------
-  // Happy path & filtering
-  // -----------------------------------------------------------------------
+  // Happy path and filtering
 
   test('valid RAI card produces zero errors', async () => {
     const markdown = validCard()
@@ -128,9 +122,7 @@ describe(raiAppCardStructure.names.join(' - '), () => {
     expect(errors.length).toBe(0)
   })
 
-  // -----------------------------------------------------------------------
-  // One negative test per validator — proves each code path fires
-  // -----------------------------------------------------------------------
+  // One negative test per validator, to prove each code path fires
 
   test('missing a required H2 section reports an error', async () => {
     const markdown = validCard()
diff --git a/src/content-linter/tests/unit/rule-filtering.ts b/src/content-linter/tests/unit/rule-filtering.ts
index 7488c5f94b76..0da64c2b514a 100644
--- a/src/content-linter/tests/unit/rule-filtering.ts
+++ b/src/content-linter/tests/unit/rule-filtering.ts
@@ -1,7 +1,6 @@
 import { describe, test, expect, vi } from 'vitest'
 import { shouldIncludeRule } from '../../scripts/lint-content'
 
-// Mock the get-rules module to provide test data for rule definitions
 vi.mock('../../lib/helpers/get-rules', () => ({
   allRules: [
     {
diff --git a/src/content-linter/tests/unit/search-replace.ts b/src/content-linter/tests/unit/search-replace.ts
index a498e4b98bbb..2cc4cd9f17d5 100644
--- a/src/content-linter/tests/unit/search-replace.ts
+++ b/src/content-linter/tests/unit/search-replace.ts
@@ -79,7 +79,6 @@ describe(searchReplace.names.join(' - '), () => {
       markdownlintOptions: { frontMatter: null }, // Include frontmatter in linting
     })
     const errors = result.markdown
-    // Should find 3 TODOCS occurrences in frontmatter
     expect(errors.length).toBe(3)
     expect(errors[0].lineNumber).toBe(2) // title: TODOCS
     expect(errors[1].lineNumber).toBe(3) // shortTitle: TODOCS
@@ -102,7 +101,6 @@ describe(searchReplace.names.join(' - '), () => {
       markdownlintOptions: { frontMatter: null }, // Include frontmatter in linting
     })
     const errors = result.markdown
-    // Should find 4 TODOCS occurrences total (2 in frontmatter + 2 in content)
     expect(errors.length).toBe(4)
     expect(errors[0].lineNumber).toBe(2) // title: TODOCS
     expect(errors[1].lineNumber).toBe(3) // intro: TODOCS

From 3342b3d446d203027657dc33a03d8776f9f33baf Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:19:23 +0000
Subject: [PATCH 07/16] Trim redundant comments in src/frame/tests and
 src/data-directory (#63263)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/data-directory/lib/data-directory.ts       |  4 ----
 src/data-directory/lib/data-schemas/index.ts   |  4 ----
 src/data-directory/lib/filename-to-key.ts      |  1 -
 src/data-directory/middleware/data-tables.ts   |  6 +-----
 .../scripts/find-orphaned-features/find.ts     |  2 +-
 src/data-directory/tests/get-data.ts           | 10 +---------
 src/data-directory/tests/orphaned-features.ts  | 18 ------------------
 src/frame/tests/find-page.ts                   |  1 -
 src/frame/tests/get-remote-json.ts             | 10 +++-------
 .../tests/non-child-pages-resolution.test.ts   | 15 +++++++--------
 src/frame/tests/page.ts                        |  2 --
 src/frame/tests/pages.ts                       |  3 ---
 src/frame/tests/resolve-carousels.test.ts      |  4 ----
 src/frame/tests/robots-txt.ts                  |  2 --
 src/frame/tests/secure-files.ts                |  2 --
 src/frame/tests/server.ts                      |  1 -
 src/frame/tests/site-tree.ts                   |  1 -
 src/frame/tests/toc-links.ts                   |  3 ---
 src/frame/tests/url-encoding.ts                |  4 ----
 19 files changed, 13 insertions(+), 80 deletions(-)

diff --git a/src/data-directory/lib/data-directory.ts b/src/data-directory/lib/data-directory.ts
index 6098eb0e7f60..05e7049d93a6 100644
--- a/src/data-directory/lib/data-directory.ts
+++ b/src/data-directory/lib/data-directory.ts
@@ -31,21 +31,17 @@ export default function dataDirectory(
 
   const mergedOpts = Object.assign({}, defaultOpts, opts)
 
-  // validate input
   assert(Array.isArray(mergedOpts.ignorePatterns))
   assert(mergedOpts.ignorePatterns.every(isRegExp))
   assert(Array.isArray(mergedOpts.extensions))
   assert(mergedOpts.extensions.length)
 
-  // start with an empty data object
   const data: DataDirectoryResult = {}
 
   // find YAML and Markdown files in the given directory, recursively
   const filenames = walk(dir, { includeBasePath: true }).filter((filename: string) => {
-    // ignore files that match any of ignorePatterns regexes
     if (mergedOpts.ignorePatterns.some((pattern) => pattern.test(filename))) return false
 
-    // ignore files that don't have a whitelisted file extension
     return mergedOpts.extensions.includes(path.extname(filename).toLowerCase())
   })
 
diff --git a/src/data-directory/lib/data-schemas/index.ts b/src/data-directory/lib/data-schemas/index.ts
index c0c394b4e8cf..bd157c2afb63 100644
--- a/src/data-directory/lib/data-schemas/index.ts
+++ b/src/data-directory/lib/data-schemas/index.ts
@@ -8,9 +8,7 @@ interface DataSchemas {
   [key: string]: string
 }
 
-// Helper function to resolve schema paths based on runtime context
 function resolveSchemaPath(filename: string): string {
-  // Check if we're in a test context
   const isTest = process.env.NODE_ENV === 'test'
 
   if (isTest) {
@@ -37,7 +35,6 @@ function loadTableSchemas(): DataSchemas {
       const schemaPath = path.join(schemasDir, `${name}.ts`)
 
       if (fs.existsSync(schemaPath)) {
-        // Use the resolver for consistent path handling
         tableSchemas[`data/tables/${yamlFile}`] = resolveSchemaPath(`tables/${name}.ts`)
       }
     }
@@ -61,7 +58,6 @@ const manualSchemas: DataSchemas = {
   'data/tables/copilot/matrix-meta.yml': resolveSchemaPath('tables/copilot/matrix-meta.ts'),
 }
 
-// Combine manual registrations with auto-discovered table schemas
 const dataSchemas: DataSchemas = {
   ...manualSchemas,
   ...loadTableSchemas(),
diff --git a/src/data-directory/lib/filename-to-key.ts b/src/data-directory/lib/filename-to-key.ts
index 2680b0ce5626..a13bf343f676 100644
--- a/src/data-directory/lib/filename-to-key.ts
+++ b/src/data-directory/lib/filename-to-key.ts
@@ -1,7 +1,6 @@
 import path from 'path'
 import { escapeRegExp } from 'lodash-es'
 
-// slash at the beginning of a filename
 const leadingPathSeparator = new RegExp(`^${escapeRegExp(path.sep)}`)
 const windowsLeadingPathSeparator = new RegExp('^/')
 
diff --git a/src/data-directory/middleware/data-tables.ts b/src/data-directory/middleware/data-tables.ts
index a29086e9f08c..8edf5262f938 100644
--- a/src/data-directory/middleware/data-tables.ts
+++ b/src/data-directory/middleware/data-tables.ts
@@ -4,7 +4,6 @@ import { getDeepDataByLanguage } from '@/data-directory/lib/get-data'
 
 let tablesCache: Record<string, unknown> | null = null
 
-// Lazy loading function
 const getTables = () => {
   if (!tablesCache) {
     // Keep product-name-heavy reference tables in English only for now
@@ -13,10 +12,7 @@ const getTables = () => {
   return tablesCache
 }
 
-/**
- * Middleware that loads data-driven table content into the request context.
- * Tables are sourced from YAML files in data/tables/ directory.
- */
+// Loads the YAML files under data/tables/ into req.context.
 export default async function dataTables(req: ExtendedRequest, res: Response, next: NextFunction) {
   if (!req.context) throw new Error('request not contextualized')
 
diff --git a/src/data-directory/scripts/find-orphaned-features/find.ts b/src/data-directory/scripts/find-orphaned-features/find.ts
index e3ca4fd3861d..2398738b896c 100644
--- a/src/data-directory/scripts/find-orphaned-features/find.ts
+++ b/src/data-directory/scripts/find-orphaned-features/find.ts
@@ -156,7 +156,7 @@ function searchAndRemove(features: Set<string>, pages: Page[], verbose = false)
   // them in, we'll need the English equivalent content to be able to
   // use the correctTranslatedContentStrings function.
 
-  // Check variables files
+  // Check the English variable files.
   for (const filePath of getVariableFiles(path.join(languages.en.dir, 'data', 'variables'))) {
     const fileContent = fs.readFileSync(filePath, 'utf-8')
     checkString(fileContent, features, { filePath, verbose, languageCode: 'en' })
diff --git a/src/data-directory/tests/get-data.ts b/src/data-directory/tests/get-data.ts
index d9f72f74a09c..7b3a0414f929 100644
--- a/src/data-directory/tests/get-data.ts
+++ b/src/data-directory/tests/get-data.ts
@@ -73,7 +73,6 @@ describe('get-data', () => {
   })
 
   test('getDataByLanguage variables English', () => {
-    // The most basic test
     {
       const result = getDataByLanguage('variables.stuff.foo', 'en')
       expect(result).toBe('Foo')
@@ -91,7 +90,6 @@ describe('get-data', () => {
   })
 
   test('getDataByLanguage variables with non-English', () => {
-    // The most basic test
     {
       const result = getDataByLanguage('variables.stuff.foo', 'ja')
       expect(result).toBe('フー')
@@ -109,7 +107,6 @@ describe('get-data', () => {
   })
 
   test('getDataByLanguage variables failures', () => {
-    // The most basic test
     {
       const result = getDataByLanguage('variables.stuff.key_non_existent', 'en')
       expect(result).toBeUndefined()
@@ -127,7 +124,6 @@ describe('get-data', () => {
   })
 
   test('getDataByLanguage reusables English', () => {
-    // The most basic test
     {
       const result = getDataByLanguage('reusables.coolness', 'en')
       expect(result).toBe('This is *Markdown*')
@@ -140,7 +136,6 @@ describe('get-data', () => {
   })
 
   test('getDataByLanguage reusables non-English', () => {
-    // The most basic test
     {
       const result = getDataByLanguage('reusables.coolness', 'ja')
       expect(result).toBe('これがマークダウンです')
@@ -153,7 +148,6 @@ describe('get-data', () => {
   })
 
   test('getDataByLanguage failures', () => {
-    // The most basic test
     {
       const result = getDataByLanguage('reusables.neverheardof', 'en')
       expect(result).toBeUndefined()
@@ -166,7 +160,6 @@ describe('get-data', () => {
   })
 
   test('getUIDataMerged', () => {
-    // The most basic test
     {
       const result = getUIDataMerged('en')
       expect(result.key).toBe('Value')
@@ -183,7 +176,6 @@ describe('get-data', () => {
   })
 
   test('getDeepDataByLanguage', () => {
-    // The most basic test
     {
       const result = getDeepDataByLanguage('variables', 'en')
       expect((result.stuff as Record<string, string>).foo).toBe('Foo')
@@ -329,7 +321,7 @@ describe('get-data applies corrections to translated variables', () => {
               name: '{% データ variables.myproduct.name %}',
             },
             phases: {
-              // Not corrupted — should pass through unchanged
+              // Not corrupted, so it should pass through unchanged
               preview: '{% ifversion ghes < 3.16 %}ベータ{% else %}パブリックプレビュー{% endif %}',
             },
           },
diff --git a/src/data-directory/tests/orphaned-features.ts b/src/data-directory/tests/orphaned-features.ts
index 404178ba5efd..ea931b6b4f21 100644
--- a/src/data-directory/tests/orphaned-features.ts
+++ b/src/data-directory/tests/orphaned-features.ts
@@ -7,7 +7,6 @@ import { describe, expect, test } from 'vitest'
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const fixturesDir = path.join(__dirname, 'orphaned-features', 'fixtures')
 
-// Import the actual helper functions from the orphaned features script
 const { getVariableFiles, getReusableFiles } =
   await import('@/data-directory/scripts/find-orphaned-features/find')
 
@@ -16,11 +15,9 @@ describe('orphaned features detection', () => {
     const variablesDir = path.join(fixturesDir, 'data', 'variables')
     const variableFiles = getVariableFiles(variablesDir)
 
-    // Should find our test.yml file
     expect(variableFiles).toHaveLength(1)
     expect(variableFiles[0]).toMatch(/test\.yml$/)
 
-    // Verify the file exists and contains expected content
     const testVariableContent = fs.readFileSync(variableFiles[0], 'utf-8')
     expect(testVariableContent).toContain('used-in-variables')
     expect(testVariableContent).toContain('ifversion')
@@ -30,11 +27,9 @@ describe('orphaned features detection', () => {
     const reusablesDir = path.join(fixturesDir, 'data', 'reusables')
     const reusableFiles = getReusableFiles(reusablesDir)
 
-    // Should find our test.md file
     expect(reusableFiles).toHaveLength(1)
     expect(reusableFiles[0]).toMatch(/test\.md$/)
 
-    // Verify the file exists and contains expected content
     const testReusableContent = fs.readFileSync(reusableFiles[0], 'utf-8')
     expect(testReusableContent).toContain('used-in-reusables')
     expect(testReusableContent).toContain('ifversion')
@@ -48,7 +43,6 @@ describe('orphaned features detection', () => {
 
     const content = fs.readFileSync(testVariableFile, 'utf-8')
 
-    // Verify the test file has the expected feature usage patterns
     expect(content).toContain('{% ifversion used-in-variables %}')
     expect(content).toContain('test_variable_with_feature')
     expect(content).toContain('complex_variable')
@@ -60,30 +54,25 @@ describe('orphaned features detection', () => {
     const nestedVariablesDir = path.join(tempDir, 'variables', 'nested')
     const nestedReusablesDir = path.join(tempDir, 'reusables', 'nested')
 
-    // Create directories
     fs.mkdirSync(nestedVariablesDir, { recursive: true })
     fs.mkdirSync(nestedReusablesDir, { recursive: true })
 
-    // Create test files
     fs.writeFileSync(path.join(nestedVariablesDir, 'nested.yml'), 'test: value')
     fs.writeFileSync(path.join(nestedReusablesDir, 'nested.md'), '# Test content')
     fs.writeFileSync(path.join(tempDir, 'variables', 'root.yml'), 'root: value')
     fs.writeFileSync(path.join(tempDir, 'reusables', 'root.md'), '# Root content')
 
     try {
-      // Test getVariableFiles with nested structure
       const variableFiles = getVariableFiles(path.join(tempDir, 'variables'))
       expect(variableFiles).toHaveLength(2)
       expect(variableFiles.some((f) => f.includes('nested.yml'))).toBe(true)
       expect(variableFiles.some((f) => f.includes('root.yml'))).toBe(true)
 
-      // Test getReusableFiles with nested structure
       const reusableFiles = getReusableFiles(path.join(tempDir, 'reusables'))
       expect(reusableFiles).toHaveLength(2)
       expect(reusableFiles.some((f) => f.includes('nested.md'))).toBe(true)
       expect(reusableFiles.some((f) => f.includes('root.md'))).toBe(true)
     } finally {
-      // Clean up
       fs.rmSync(tempDir, { recursive: true, force: true })
     }
   })
@@ -93,7 +82,6 @@ describe('orphaned features detection', () => {
     const tempDir = path.join(__dirname, 'temp-mixed-files')
     fs.mkdirSync(tempDir, { recursive: true })
 
-    // Create various file types
     fs.writeFileSync(path.join(tempDir, 'test.yml'), 'yml: content')
     fs.writeFileSync(path.join(tempDir, 'test.md'), '# MD content')
     fs.writeFileSync(path.join(tempDir, 'test.json'), '{"json": true}')
@@ -112,7 +100,6 @@ describe('orphaned features detection', () => {
       expect(reusableFiles).toHaveLength(1)
       expect(reusableFiles[0]).toMatch(/test\.md$/)
     } finally {
-      // Clean up
       fs.rmSync(tempDir, { recursive: true, force: true })
     }
   })
@@ -128,11 +115,9 @@ describe('orphaned features detection', () => {
     expect(fs.existsSync(path.join(featuresDir, 'used-in-variables.yml'))).toBe(true)
     expect(fs.existsSync(path.join(featuresDir, 'truly-orphaned.yml'))).toBe(true)
 
-    // Check that the variable file references the feature
     const variableContent = fs.readFileSync(path.join(variablesDir, 'test.yml'), 'utf-8')
     expect(variableContent).toContain('used-in-variables')
 
-    // Verify that the getVariableFiles function would find this file
     const variableFiles = getVariableFiles(variablesDir)
     expect(variableFiles.length).toBeGreaterThan(0)
 
@@ -152,7 +137,6 @@ describe('orphaned features detection', () => {
     const tempDir = path.join(__dirname, 'temp-mixed-target-files')
     fs.mkdirSync(tempDir, { recursive: true })
 
-    // Create files that both functions might encounter
     fs.writeFileSync(
       path.join(tempDir, 'variables.yml'),
       'var: {% ifversion test-feature %}enabled{% endif %}',
@@ -174,11 +158,9 @@ describe('orphaned features detection', () => {
       expect(reusableFiles).toHaveLength(1)
       expect(reusableFiles[0]).toMatch(/reusable\.md$/)
 
-      // Verify no cross-contamination
       expect(variableFiles.some((f) => f.endsWith('.md'))).toBe(false)
       expect(reusableFiles.some((f) => f.endsWith('.yml'))).toBe(false)
     } finally {
-      // Clean up
       fs.rmSync(tempDir, { recursive: true, force: true })
     }
   })
diff --git a/src/frame/tests/find-page.ts b/src/frame/tests/find-page.ts
index 8ecc9b24a282..513abc22e81a 100644
--- a/src/frame/tests/find-page.ts
+++ b/src/frame/tests/find-page.ts
@@ -25,7 +25,6 @@ describe('find page', () => {
     }
     const redirectToFind = '/some-old-path'
 
-    // add named keys
     const pageMap = {
       [englishPermalink]: page,
     }
diff --git a/src/frame/tests/get-remote-json.ts b/src/frame/tests/get-remote-json.ts
index 6776f924c29e..f7e3a33825f3 100644
--- a/src/frame/tests/get-remote-json.ts
+++ b/src/frame/tests/get-remote-json.ts
@@ -8,11 +8,8 @@ import nock from 'nock'
 
 import getRemoteJSON, { cache } from '@/frame/lib/get-remote-json'
 
-/**
- *
- * These unit tests test that the in-memory cache works and when it's
- * not a cache it, it can benefit from using the disk cache.
- */
+// Covers the in-memory cache, and the fallback to the disk cache when memory
+// misses.
 
 describe('getRemoteJSON', () => {
   const envVarValueBefore = process.env.GET_REMOTE_JSON_DISK_CACHE_ROOT
@@ -69,7 +66,6 @@ describe('getRemoteJSON', () => {
     nock(origin).get(pathname).reply(200, { cool: true })
     await getRemoteJSON(url, {})
 
-    // Make every file in the cache directory an empty file
     for (const file of fs.readdirSync(tempTempDir)) {
       fs.writeFileSync(path.join(tempTempDir, file), '')
     }
@@ -91,7 +87,7 @@ describe('getRemoteJSON', () => {
     nock(origin).get(pathname).reply(200, { cool: true })
     await getRemoteJSON(url, {})
 
-    // Make every file in the cache directory an empty file
+    // Corrupt every cached file so the disk cache can't be parsed.
     for (const file of fs.readdirSync(tempTempDir)) {
       fs.writeFileSync(path.join(tempTempDir, file), '{"not:JSON{')
     }
diff --git a/src/frame/tests/non-child-pages-resolution.test.ts b/src/frame/tests/non-child-pages-resolution.test.ts
index 0e3d91311dfd..47fe3c6fd6e9 100644
--- a/src/frame/tests/non-child-pages-resolution.test.ts
+++ b/src/frame/tests/non-child-pages-resolution.test.ts
@@ -2,15 +2,15 @@ import { describe, expect, test } from 'vitest'
 import path from 'path'
 import fs from 'fs'
 
-// ROOT is the project root directory
-// From src/frame/tests/ -> ../../.. gets to project root
 const ROOT = path.resolve(__dirname, '../../..')
 
-/**
- * Tests for non-child page resolution:
- * `/content/` prefix in children frontmatter resolves to absolute content paths,
- * allowing cross-product directory and article inclusion.
- */
+// Tests for non-child page resolution: a `/content/` prefix in children
+// frontmatter resolves to an absolute content path, which is what lets a page
+// pull in a directory or article from another product.
+//
+// Note this file imports no production code. The behaviour tests reimplement
+// logic from create-tree.ts and current-product-tree.ts, and the rest only check
+// that fixture files exist, so none of it exercises the real resolution path.
 
 describe('Non-child page resolution', () => {
   describe('/content/ prefix in children frontmatter', () => {
@@ -147,7 +147,6 @@ describe('Non-child page resolution', () => {
       // The actual translation is handled by the page loading system
       const child = '/content/actions/using-workflows/storing-workflow-data-as-artifacts'
 
-      // Path should not include language prefix
       expect(child.startsWith('/content/')).toBe(true)
       expect(child).not.toMatch(/\/content\/(en|ja|es|pt|zh|ru|ko|fr|de)\//)
     })
diff --git a/src/frame/tests/page.ts b/src/frame/tests/page.ts
index 389a088a9238..0db58d2894ec 100644
--- a/src/frame/tests/page.ts
+++ b/src/frame/tests/page.ts
@@ -89,7 +89,6 @@ describe('Page class', () => {
         basePath: path.join(__dirname, '../../../src/fixtures/fixtures'),
         languageCode: 'en',
       })
-      // set version to the latest enterprise version
       const context: TestContext = {
         currentVersion: `enterprise-server@${enterpriseServerReleases.latest}`,
         currentLanguage: 'en',
@@ -139,7 +138,6 @@ describe('Page class', () => {
         basePath: path.join(__dirname, '../../../src/fixtures/fixtures'),
         languageCode: 'en',
       })
-      // set version to 3.0
       const context: TestContext = {
         currentVersion: 'enterprise-server@3.0',
         currentLanguage: 'en',
diff --git a/src/frame/tests/pages.ts b/src/frame/tests/pages.ts
index 2ae7279cee64..913c49cd5364 100644
--- a/src/frame/tests/pages.ts
+++ b/src/frame/tests/pages.ts
@@ -54,7 +54,6 @@ describe('pages module', () => {
         .map((page) => pick(page, ['redirect_from', 'applicableVersions', 'fullPath']))
         .value()
 
-      // Map from redirect path to Set of file paths
       const redirectToFiles = new Map<string, Set<string>>()
       const versionedRedirects: Array<{ path: string; file: string }> = []
 
@@ -78,7 +77,6 @@ describe('pages module', () => {
         .filter(([, files]) => files.size > 1)
         .map(([redirectPath]) => redirectPath)
 
-      // Build a detailed message with sources for each duplicate
       const message = `Found ${duplicates.length} duplicate redirect_from path${duplicates.length === 1 ? '' : 's'}.
         Ensure that you don't define the same path more than once in the redirect_from property in a single file and across all English files.
         You may also receive this error if you have defined the same children property more than once.\n${duplicates
@@ -128,7 +126,6 @@ describe('pages module', () => {
 
     test('every page has valid frontmatter', async () => {
       const frontmatterErrors = chain(pages)
-        // .filter(page => page.languageCode === 'en')
         // Page class has dynamic error properties like 'frontmatterErrors' not in type definition
         .map((page) => (page as Record<string, unknown>).frontmatterErrors)
         .filter(Boolean)
diff --git a/src/frame/tests/resolve-carousels.test.ts b/src/frame/tests/resolve-carousels.test.ts
index 683b2ba3fac0..d185c24c10b6 100644
--- a/src/frame/tests/resolve-carousels.test.ts
+++ b/src/frame/tests/resolve-carousels.test.ts
@@ -4,12 +4,10 @@ import type { ExtendedRequest, Page, ResolvedArticle } from '@/types'
 import findPage from '@/frame/lib/find-page'
 import resolveCarousels from '../middleware/resolve-carousels'
 
-// Mock the findPage function
 vi.mock('@/frame/lib/find-page', () => ({
   default: vi.fn(),
 }))
 
-// Mock the renderContent function
 vi.mock('@/content-render/index', () => ({
   renderContent: vi.fn((content, _context, options) => {
     // When textOnly is true, return plain text (no HTML wrapper)
@@ -337,7 +335,6 @@ describe('resolveCarousels middleware', () => {
   })
 
   test('should filter out articles not available in current version', async () => {
-    // Create a test page that is only available in fpt, not ghec
     const fptOnlyPage: Partial<import('@/types').Page> = {
       title: 'FPT Only Article',
       intro: 'This article is only for FPT',
@@ -347,7 +344,6 @@ describe('resolveCarousels middleware', () => {
 
     mockFindPage.mockReturnValue(fptOnlyPage as unknown as Page)
 
-    // Create a request context where we're viewing the GHEC version
     const req = createMockRequest(
       { rawCarousels: { recommended: ['/test/fpt-only'] } },
       {
diff --git a/src/frame/tests/robots-txt.ts b/src/frame/tests/robots-txt.ts
index 9ff00c5bcf95..1ef716eda4a7 100644
--- a/src/frame/tests/robots-txt.ts
+++ b/src/frame/tests/robots-txt.ts
@@ -3,7 +3,6 @@ import { describe, expect, test, vi } from 'vitest'
 import { makeLanguageSurrogateKey } from '@/frame/middleware/set-fastly-surrogate-key'
 import { get } from '@/tests/helpers/e2etest'
 
-// Type alias for the response from e2etest helper
 type TestResponse = {
   body: string
   statusCode: number
@@ -36,7 +35,6 @@ describe('robots.txt', () => {
 
   test('validates robots.txt format', async () => {
     const res: TestResponse = await get('/robots.txt')
-    // Should be valid robots.txt format
     expect(res.body).toMatch(/^User-agent: \*/)
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toMatch(/text\/plain/)
diff --git a/src/frame/tests/secure-files.ts b/src/frame/tests/secure-files.ts
index 9b0f6105d7ad..f741ee91df2d 100644
--- a/src/frame/tests/secure-files.ts
+++ b/src/frame/tests/secure-files.ts
@@ -29,11 +29,9 @@ const codeOwners = codeOwnersFile.split(/\r?\n/)
 describe('Secure file paths are present and have code owners if required', () => {
   for (const file of secureFiles) {
     test(`secure file(s) check for: ${file.name}`, async () => {
-      // Verify file(s) exist in provided path
       const matchingFiles = await glob(file.path)
       expect(matchingFiles.length, `Expected to find content in "${file.path}"`).toBeGreaterThan(0)
 
-      // Verify there are code owners for file(s)
       if (file.requiredCodeOwner) {
         const matchingEntry = codeOwners.find((entry) => entry.includes(file.path))
         expect(
diff --git a/src/frame/tests/server.ts b/src/frame/tests/server.ts
index 2226ec875950..8543c653d313 100644
--- a/src/frame/tests/server.ts
+++ b/src/frame/tests/server.ts
@@ -181,7 +181,6 @@ describe('server', () => {
     const res = await get('/categories.json')
     expect(res.statusCode).toBe(200)
 
-    // check for CORS header
     expect(res.headers['access-control-allow-origin']).toBe('*')
 
     // Check that it can be cached at the CDN
diff --git a/src/frame/tests/site-tree.ts b/src/frame/tests/site-tree.ts
index 5637b026789f..a62099e603be 100644
--- a/src/frame/tests/site-tree.ts
+++ b/src/frame/tests/site-tree.ts
@@ -74,7 +74,6 @@ function validate(currentPage: Tree): void {
 
     expect(isValid, errors).toBe(true)
 
-    // Run recursively until we run out of child pages
     validate(pageRef)
   }
 }
diff --git a/src/frame/tests/toc-links.ts b/src/frame/tests/toc-links.ts
index 16dc42c754c4..96fce3fd2c56 100644
--- a/src/frame/tests/toc-links.ts
+++ b/src/frame/tests/toc-links.ts
@@ -20,11 +20,9 @@ describe('toc links', () => {
 
     for (const pageVersion of Object.keys(allVersions)) {
       for (const page of englishIndexPages) {
-        // skip page if it doesn't have a permalink for the current product version
         if (!page.permalinks.some((permalink: Permalink) => permalink.pageVersion === pageVersion))
           continue
 
-        // build fake context object for rendering the page
         const context = {
           page,
           pages,
@@ -34,7 +32,6 @@ describe('toc links', () => {
           currentVersionObj: allVersions[pageVersion],
         }
 
-        // ensure all toc pages can render
         try {
           await renderContent(page.markdown, context)
         } catch (err) {
diff --git a/src/frame/tests/url-encoding.ts b/src/frame/tests/url-encoding.ts
index 327066098ffa..2c4d0e8d32c9 100644
--- a/src/frame/tests/url-encoding.ts
+++ b/src/frame/tests/url-encoding.ts
@@ -14,7 +14,6 @@ describe('URL encoding for version paths', () => {
     expect([200, 301, 302]).toContain(res.statusCode)
 
     if (res.statusCode === 301 || res.statusCode === 302) {
-      // If it redirects, it should redirect to the decoded version
       expect(res.headers.location).toBe('/en/enterprise-cloud@latest/copilot/concepts/chat')
     }
   })
@@ -34,17 +33,14 @@ describe('URL encoding for version paths', () => {
   })
 
   test('handles URL-encoded @ symbol in second path segment', async () => {
-    // When no language prefix is present
     const encodedUrl = '/enterprise-cloud%40latest/copilot/concepts/chat'
     const res = await get(encodedUrl)
 
-    // Should redirect to add language prefix and decode
     expect([301, 302]).toContain(res.statusCode)
     expect(res.headers.location).toBe('/en/enterprise-cloud@latest/copilot/concepts/chat')
   })
 
   test('normal @ symbol paths continue to work', async () => {
-    // Ensure we don't break existing functionality
     const normalUrl = '/en/enterprise-cloud@latest/copilot/concepts/chat'
     const res = await get(normalUrl)
 

From 2701956ca4ea07258e20fc0756332fe681e00050 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:19:30 +0000
Subject: [PATCH 08/16] Trim redundant comments in src/frame/components
 (#63262)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/frame/components/CodeTabsGroup.tsx         | 10 +++++-----
 src/frame/components/DefaultLayout.module.scss |  2 +-
 src/frame/components/DefaultLayout.tsx         |  8 +++-----
 src/frame/components/HighlightedCode.tsx       |  4 ++--
 src/frame/components/UtmPreserver.tsx          |  9 ---------
 .../components/context/ArticleContext.tsx      |  2 +-
 .../context/CategoryLandingContext.tsx         |  2 +-
 .../components/context/TocLandingContext.tsx   |  2 +-
 src/frame/components/lib/prefetch.ts           |  2 +-
 src/frame/components/lib/toggle-annotations.ts | 18 +++++-------------
 .../components/page-footer/Contribution.tsx    |  2 +-
 .../page-footer/DocsFooter.module.scss         | 14 +++++++-------
 .../components/page-footer/DocsFooter.tsx      |  4 ++--
 .../page-footer/FooterDivider.module.scss      |  2 +-
 .../components/page-footer/FooterDivider.tsx   |  2 +-
 src/frame/components/page-footer/Support.tsx   |  2 +-
 .../page-footer/SupportSection.module.scss     | 18 +++++++++---------
 .../components/page-footer/SupportSection.tsx  |  2 +-
 .../BreadcrumbsScroller.module.scss            |  8 ++++----
 .../page-header/BreadcrumbsScroller.tsx        | 18 +++++++++---------
 .../page-header/DocsSecondaryBar.module.scss   |  2 +-
 .../page-header/HeaderNotifications.tsx        |  8 +++-----
 .../sidebar/SidebarCollapseContext.tsx         | 10 +++++-----
 .../components/sidebar/SidebarNav.module.scss  |  6 +++---
 src/frame/components/sidebar/SidebarNav.tsx    |  9 +++++----
 .../UnrenderedMarkdownContent.tsx              |  8 --------
 .../ui/ScrollButton/ScrollButton.tsx           |  5 ++---
 27 files changed, 75 insertions(+), 104 deletions(-)

diff --git a/src/frame/components/CodeTabsGroup.tsx b/src/frame/components/CodeTabsGroup.tsx
index 2d326d26eb03..d6b701399090 100644
--- a/src/frame/components/CodeTabsGroup.tsx
+++ b/src/frame/components/CodeTabsGroup.tsx
@@ -27,11 +27,11 @@ import { useTranslation } from '@/languages/components/useTranslation'
 // React-native replacement for the imperative CodeTabs enhancer (#6619). The old
 // component scanned `#article-contents` for `.ghd-codetabs`, inserted a foreign
 // `.ghd-codetabs-nav` mountPoint as the container's first child, portaled a nav
-// into it, and toggled panel attributes — destructive surgery on React-owned
-// nodes that breaks on client-side navigation teardown. Instead, the article body
-// hast maps each `.ghd-codetabs` container to <CodeTabsGroup>, which reads its
-// `.ghd-codetab` panel children straight from props and renders the nav + panels
-// itself. No DOM scanning, no portal, no foreign nodes.
+// into it, and toggled panel attributes. Those mutations are destructive surgery
+// on React-owned nodes and break on client-side navigation teardown. Instead, the
+// article body hast maps each `.ghd-codetabs` container to <CodeTabsGroup>, which
+// reads its `.ghd-codetab` panel children straight from props and renders the nav
+// and panels itself. No DOM scanning, no portal, no foreign nodes.
 //
 // The selected language lives in CodeLanguageContext so multiple code-tab groups
 // on one page stay in sync and share the language cookie, matching the previous
diff --git a/src/frame/components/DefaultLayout.module.scss b/src/frame/components/DefaultLayout.module.scss
index f6dea1f56509..d71ccc296c89 100644
--- a/src/frame/components/DefaultLayout.module.scss
+++ b/src/frame/components/DefaultLayout.module.scss
@@ -14,7 +14,7 @@
   }
 }
 
-// When the inline mobile/tablet nav is open, it takes over the viewport — hide
+// When the inline mobile/tablet nav is open, it takes over the viewport, so hide
 // the content column so the full-width rail isn't squeezed beside it. Above the
 // xxl breakpoint the rail is a fixed-width sibling, so content always shows.
 .contentHiddenForNav {
diff --git a/src/frame/components/DefaultLayout.tsx b/src/frame/components/DefaultLayout.tsx
index 133e2f7b4467..ea174a327aa8 100644
--- a/src/frame/components/DefaultLayout.tsx
+++ b/src/frame/components/DefaultLayout.tsx
@@ -117,9 +117,7 @@ export const DefaultLayout = (props: Props) => {
     return getCategoryImageUrl('default')
   }
 
-  // Helper function to build API article URLs with proper query parameter handling
   function buildApiArticleUrl(apiPath: string): string {
-    // Parse router.asPath to separate pathname and query parameters
     const [pathname, queryString] = router.asPath.split('?')
     const fullPathname = `/${router.locale}${pathname}`
     const queryParams = queryString ? `&${queryString}` : ''
@@ -256,7 +254,7 @@ const LayoutBody = ({ children }: LayoutBodyProps) => {
   const { collapsed, mobileNavOpen } = useSidebarCollapsed()
   const { currentProduct } = useMainContext()
   // Matches SidebarNav's own gate rather than testing router.route. There are two search
-  // pages — src/pages/search.tsx and src/pages/[versionId]/search.tsx — so a route test
+  // pages, src/pages/search.tsx and src/pages/[versionId]/search.tsx, so a route test
   // for '/search' misses every versioned search URL, and this check would then disagree
   // with SidebarNav about whether the rail is a facet rail.
   const isSearchResultsPage = currentProduct?.id === 'search'
@@ -266,8 +264,8 @@ const LayoutBody = ({ children }: LayoutBodyProps) => {
     // gets an earlier split of its own. Route-gated, so no other page moves.
     <div className={cx('d-lg-flex', isSearchResultsPage && styles.searchColumns)}>
       {/* `collapsed` is the desktop rail-collapse state (persisted). The inline
-        mobile nav is independent, so still render the sidebar when it's open —
-        otherwise opening the mobile nav while the desktop rail is collapsed
+        mobile nav is independent, so still render the sidebar when it's open.
+        Otherwise opening the mobile nav while the desktop rail is collapsed
         hides the content column (contentHiddenForNav) with no drawer to show,
         so the open nav displays a blank area instead of the doc tree.
 
diff --git a/src/frame/components/HighlightedCode.tsx b/src/frame/components/HighlightedCode.tsx
index 4e5d2c7a31a6..db1d48207990 100644
--- a/src/frame/components/HighlightedCode.tsx
+++ b/src/frame/components/HighlightedCode.tsx
@@ -10,8 +10,8 @@ import cx from 'classnames'
 
 // React-native replacement for the imperative ClientSideHighlightJS enhancer
 // (#6619). The old enhancer scanned the document for `[data-highlight] code` and
-// called `hljs.highlightElement`, which REPLACES the `<code>`'s innerHTML —
-// destructive on a React-owned node. Instead, components that render code
+// called `hljs.highlightElement`, which REPLACES the `<code>`'s innerHTML.
+// That is destructive on a React-owned node. Instead, components that render code
 // (RestCodeSamples, Webhook) use <HighlightedCode>, which highlights with
 // `lowlight` (the hast-based highlighter behind rehype-highlight) and renders the
 // tokens as real React elements via `toJsxRuntime`. No innerHTML, no DOM scan.
diff --git a/src/frame/components/UtmPreserver.tsx b/src/frame/components/UtmPreserver.tsx
index e92aad49f6bb..a6805d4bf64a 100644
--- a/src/frame/components/UtmPreserver.tsx
+++ b/src/frame/components/UtmPreserver.tsx
@@ -5,7 +5,6 @@ export const UtmPreserver = () => {
   const router = useRouter()
 
   useEffect(() => {
-    // Extract UTM parameters from current URL
     const getUtmParams = (): URLSearchParams => {
       const urlParams = new URLSearchParams(window.location.search)
       const utmParams = new URLSearchParams()
@@ -22,7 +21,6 @@ export const UtmPreserver = () => {
     const utmParams = getUtmParams()
     if (utmParams.toString() === '') return
 
-    // Check if a link should have UTM parameters preserved
     const shouldPreserveUtm = (url: string): boolean => {
       const lowercaseUrl = url.toLowerCase()
 
@@ -35,7 +33,6 @@ export const UtmPreserver = () => {
       return hasProtocol && isGithubCom && !isDocsGithubCom
     }
 
-    // Add UTM parameters to a URL
     const addUtmParamsToUrl = (url: string, params: URLSearchParams): string => {
       try {
         const urlObj = new URL(url)
@@ -46,12 +43,10 @@ export const UtmPreserver = () => {
 
         return urlObj.toString()
       } catch {
-        // If URL parsing fails, return original URL
         return url
       }
     }
 
-    // Apply UTM parameters to relevant links
     const applyUtmToLinks = (): void => {
       const links = document.querySelectorAll<HTMLAnchorElement>('a[href]')
 
@@ -62,7 +57,6 @@ export const UtmPreserver = () => {
       }
     }
 
-    // Handle click events for dynamic link modification
     const handleLinkClick = (event: Event): void => {
       const link = (event.target as Element)?.closest('a') as HTMLAnchorElement
       if (!link || !link.href) return
@@ -72,7 +66,6 @@ export const UtmPreserver = () => {
       }
     }
 
-    // Apply UTM parameters immediately to existing links
     applyUtmToLinks()
 
     // Also handle clicks for any dynamically added links
@@ -86,13 +79,11 @@ export const UtmPreserver = () => {
 
     router.events.on('routeChangeComplete', handleRouteChange)
 
-    // Cleanup
     return () => {
       document.removeEventListener('click', handleLinkClick, true)
       router.events.off('routeChangeComplete', handleRouteChange)
     }
   }, [router.asPath, router.events])
 
-  // This component doesn't render anything
   return null
 }
diff --git a/src/frame/components/context/ArticleContext.tsx b/src/frame/components/context/ArticleContext.tsx
index 2b84f53b0a95..3582e7047469 100644
--- a/src/frame/components/context/ArticleContext.tsx
+++ b/src/frame/components/context/ArticleContext.tsx
@@ -55,7 +55,7 @@ const PagePathToVaFlowMapping: Record<string, string> = {
     'pages_ssl_check',
 }
 
-// Request type for context extraction — uses Record<string, unknown> for the page
+// Request type for context extraction. Uses Record<string, unknown> for the page
 // because the Page type doesn't include all runtime-computed properties.
 interface ContextRequest {
   context: {
diff --git a/src/frame/components/context/CategoryLandingContext.tsx b/src/frame/components/context/CategoryLandingContext.tsx
index 41da55f48f96..d92d382fb29d 100644
--- a/src/frame/components/context/CategoryLandingContext.tsx
+++ b/src/frame/components/context/CategoryLandingContext.tsx
@@ -32,7 +32,7 @@ export const useCategoryLandingContext = (): CategoryLandingContextT => {
   return context
 }
 
-// Request type for context extraction — uses Record<string, unknown> for the page
+// Request type for context extraction. Uses Record<string, unknown> for the page
 // because the Page type doesn't include all runtime-computed properties.
 interface ContextRequest {
   context: {
diff --git a/src/frame/components/context/TocLandingContext.tsx b/src/frame/components/context/TocLandingContext.tsx
index 7864f3bbbf5b..e69284f5b784 100644
--- a/src/frame/components/context/TocLandingContext.tsx
+++ b/src/frame/components/context/TocLandingContext.tsx
@@ -27,7 +27,7 @@ export const useTocLandingContext = (): TocLandingContextT => {
   return context
 }
 
-// Request type for context extraction — uses Record<string, unknown> for the page
+// Request type for context extraction. Uses Record<string, unknown> for the page
 // because the Page type doesn't include all runtime-computed properties.
 interface ContextRequest {
   context: {
diff --git a/src/frame/components/lib/prefetch.ts b/src/frame/components/lib/prefetch.ts
index 84f7b3833a0c..7213b3cacca0 100644
--- a/src/frame/components/lib/prefetch.ts
+++ b/src/frame/components/lib/prefetch.ts
@@ -4,7 +4,7 @@ import type { useRouter } from 'next/router'
 type Router = ReturnType<typeof useRouter>
 
 // Session-lived de-dupe set. Module scope (not a per-component useRef) so it
-// survives the sidebar's per-navigation remount — otherwise the cache would
+// survives the sidebar's per-navigation remount. Otherwise the cache would
 // reset every nav and "de-duped per href" would only hold within a single page.
 // Bounded by the number of distinct internal hrefs the user hovers/focuses.
 const prefetchedHrefs = new Set<string>()
diff --git a/src/frame/components/lib/toggle-annotations.ts b/src/frame/components/lib/toggle-annotations.ts
index cdce002b7821..628391ec7c1e 100644
--- a/src/frame/components/lib/toggle-annotations.ts
+++ b/src/frame/components/lib/toggle-annotations.ts
@@ -8,15 +8,9 @@ enum annotationMode {
   Inline = 'inline',
 }
 
-/**
- * Validates if a given mode is one of expected annotation modes. If no acceptable mode is found, a default mode is returned.. Optionally, returns a default mode.
- * @param mode The mode to validate, ideally "#annotation-beside" or "#annotation-inline"
- * @param leaveNull Alters the return value of this function. If false, the function will return the mode that was passed in or, in the case of null, the default mode. If true, the function will return null instead of using the default mode.
- * @returns The validated mode, or null if leaveNull is true and no valid mode is found.
- */
+// Returns the mode if it is 'beside' or 'inline', otherwise falls back to Beside.
 function validateMode(mode?: string) {
   if (mode === annotationMode.Beside || mode === annotationMode.Inline) return mode
-  // default to Beside
   else return annotationMode.Beside
 }
 
@@ -24,15 +18,13 @@ export default function toggleAnnotation() {
   const annotationButtons = Array.from(document.querySelectorAll('.annotate-toggle button'))
   if (!annotationButtons.length) return
 
-  const cookie = validateMode(Cookies.get(ANNOTATE_MODE_COOKIE_NAME)) // will default to beside
+  const cookie = validateMode(Cookies.get(ANNOTATE_MODE_COOKIE_NAME))
   displayAnnotationMode(annotationButtons, cookie)
 
-  // this loop adds event listeners for both the annotation buttons
   for (const annotationBtn of annotationButtons) {
     annotationBtn.addEventListener('click', (evt) => {
       evt.preventDefault()
 
-      // validate the annotation mode and set the cookie with the valid mode
       const validMode = validateMode(annotationBtn.getAttribute('value')!)
       Cookies.set(ANNOTATE_MODE_COOKIE_NAME, validMode!)
       sendEvent({
@@ -41,14 +33,15 @@ export default function toggleAnnotation() {
         preference_value: validMode,
       })
 
-      // set and display the annotation mode
       setActive(annotationButtons, validMode)
       displayAnnotationMode(annotationButtons, validMode)
     })
   }
 }
 
-// sets the active element's aria-current, if no targetMode is set we default to "Beside", errors if it can't set either Beside or the passed in targetMode
+// Sets aria-current on every button whose value matches the validated mode, and
+// clears it from the rest. Missing or invalid modes validate to Beside. Throws if
+// no button matches.
 function setActive(annotationButtons: Array<Element>, targetMode?: string) {
   const activeElements: Array<Element> = []
   targetMode = validateMode(targetMode)
@@ -69,7 +62,6 @@ function setActive(annotationButtons: Array<Element>, targetMode?: string) {
   return activeElements
 }
 
-// displays the chosen annotation mode
 function displayAnnotationMode(annotationBtnItems: Array<Element>, targetMode?: string) {
   if (!targetMode || targetMode === annotationMode.Beside) {
     for (const el of annotationBtnItems) {
diff --git a/src/frame/components/page-footer/Contribution.tsx b/src/frame/components/page-footer/Contribution.tsx
index 5fdb93ab3243..0468a0dfd5f8 100644
--- a/src/frame/components/page-footer/Contribution.tsx
+++ b/src/frame/components/page-footer/Contribution.tsx
@@ -10,7 +10,7 @@ export const Contribution = () => {
     : 'https://github.com/github/docs'
 
   // Heading and body styling comes from the footer column rules in
-  // SupportSection.module.scss — the Docs 2026 design renders these as plain body
+  // SupportSection.module.scss. The Docs 2026 design renders these as plain body
   // text rather than a bold heading plus muted copy.
   return (
     <div className="f5 contribution">
diff --git a/src/frame/components/page-footer/DocsFooter.module.scss b/src/frame/components/page-footer/DocsFooter.module.scss
index 740cd196179c..bd9d633f43b8 100644
--- a/src/frame/components/page-footer/DocsFooter.module.scss
+++ b/src/frame/components/page-footer/DocsFooter.module.scss
@@ -1,7 +1,7 @@
 // In dark mode the footer sits on the repo's canvas (#0d1117) while brand's
 // canvas-subtle comes from brand's own palette (#0f1511). Those are near-identical,
 // so the controls would lose their fill and read as bare outlines. Use Primer's
-// surfaces there instead — they're built to contrast with this background. Selector
+// surfaces there instead: they're built to contrast with this background. Selector
 // pattern follows octicon-table-optimization.scss.
 @mixin footer-control-surfaces-dark {
   --color-btn-bg: var(--color-canvas-subtle);
@@ -21,8 +21,8 @@
   // a visibly darker slab.
   --brand-footer-bg-color: var(--bgColor-default, var(--color-canvas-default));
 
-  // The design draws all four footer controls — Yes, No, Make a contribution and
-  // Back to top — on brand's subtle canvas with a subtle border (#f2f5f3 on #d2d9d4,
+  // The design draws all four footer controls (Yes, No, Make a contribution and
+  // Back to top) on brand's subtle canvas with a subtle border (#f2f5f3 on #d2d9d4,
   // which is exactly what these brand tokens resolve to).
   //
   // Yes/No and the contribution CTA are Primer `.btn`s, so set the variables they
@@ -48,7 +48,7 @@
   }
 
   // The band above supplies the visual break, and the design puts a 2px emphasized
-  // rule directly beneath it — on the footer's own top edge. Brand's default here is
+  // rule directly beneath it, on the footer's own top edge. Brand's default here is
   // a much brighter green (scale-green-3), so this stays an explicit override.
   border-top: 2px solid var(--brand-color-text-emphasized);
 
@@ -62,8 +62,8 @@
   }
 
   // Help region: the columns own their padding, so the section adds none. Without
-  // this the columns sit 32px below the rule that introduces them, and — because the
-  // rules between rows are column borders — those rules would stop short of the
+  // this the columns sit 32px below the rule that introduces them, and because the
+  // rules between rows are column borders, those rules would stop short of the
   // footer edges instead of spanning it as the design shows. The inline inset moves
   // onto the columns in SupportSection.module.scss so content stays aligned with the
   // top and bottom bars.
@@ -107,7 +107,7 @@
 
 // Narrow: the design stacks the legal links above the copyright, and gives each its
 // own band separated by a rule that spans the footer. So the bottom section hands its
-// padding to the two rows — the same move the help region makes — which lets the rule
+// padding to the two rows, the same move the help region makes, which lets the rule
 // between them reach the edges while both rows stay inset and aligned with each other.
 @media (max-width: 767px) {
   .docsFooter > div:has(.bottomRow) > section {
diff --git a/src/frame/components/page-footer/DocsFooter.tsx b/src/frame/components/page-footer/DocsFooter.tsx
index 995040c7429a..d2c29cdbd782 100644
--- a/src/frame/components/page-footer/DocsFooter.tsx
+++ b/src/frame/components/page-footer/DocsFooter.tsx
@@ -16,8 +16,8 @@ import styles from './DocsFooter.module.scss'
 // The design puts the legal links in the *bottom* row beside the copyright.
 // MinimalFooter.Link children render in the top row instead, and the two rows live
 // in separate DOM subtrees so no amount of CSS moves one into the other. Passing the
-// links through `copyrightStatement` — which accepts a ReactElement and renders in
-// the bottom row — gets the designed layout without overriding brand internals.
+// links through `copyrightStatement`, which accepts a ReactElement and renders in
+// the bottom row, gets the designed layout without overriding brand internals.
 // It also sidesteps the component's hard cap of five links.
 //
 // Note `copyrightStatement` is rendered inside a <Text as="p">, so everything here
diff --git a/src/frame/components/page-footer/FooterDivider.module.scss b/src/frame/components/page-footer/FooterDivider.module.scss
index fe72c7ba7aad..8abcc81481f6 100644
--- a/src/frame/components/page-footer/FooterDivider.module.scss
+++ b/src/frame/components/page-footer/FooterDivider.module.scss
@@ -17,7 +17,7 @@
 // Scroll reveal. `.armed` is only applied by the component once it knows scripting is
 // running and the band is still below the fold, so the resting state above stays
 // visible for everyone else. Opacity and transform are compositor-only, so the rise
-// does not reflow the footer beneath it — and MinimalFooter is positioned, so the
+// does not reflow the footer beneath it. MinimalFooter is positioned, so the
 // band slides under it rather than over it.
 .armed {
   opacity: 0;
diff --git a/src/frame/components/page-footer/FooterDivider.tsx b/src/frame/components/page-footer/FooterDivider.tsx
index 4e5ad2202c9b..f592227610d2 100644
--- a/src/frame/components/page-footer/FooterDivider.tsx
+++ b/src/frame/components/page-footer/FooterDivider.tsx
@@ -7,7 +7,7 @@ import styles from './FooterDivider.module.scss'
 // Purely ornamental, so it carries no accessible name and is hidden from AT.
 //
 // It fades and rises into place the first time it scrolls into view. The band is
-// only *armed* — that is, hidden — once we know scripting is running and it is still
+// only *armed* (hidden) once we know scripting is running and it is still
 // below the fold, so it can never be left permanently invisible: without JavaScript,
 // with reduced motion, or on a page short enough that the footer is already on
 // screen, it just renders in place with no animation.
diff --git a/src/frame/components/page-footer/Support.tsx b/src/frame/components/page-footer/Support.tsx
index 2411831f0378..97978e67036e 100644
--- a/src/frame/components/page-footer/Support.tsx
+++ b/src/frame/components/page-footer/Support.tsx
@@ -7,7 +7,7 @@ import { useMainContext } from '@/frame/components/context/MainContext'
 import styles from './SupportSection.module.scss'
 
 // The footer's help column. Expert services and Blog moved here out of the legal
-// strip in the Docs 2026 design — the design groups these with the other help
+// strip in the Docs 2026 design, which groups these with the other help
 // destinations.
 //
 // Below the 2-column breakpoint the design collapses this into a disclosure. Rather
diff --git a/src/frame/components/page-footer/SupportSection.module.scss b/src/frame/components/page-footer/SupportSection.module.scss
index 452fc4e16c37..e674cc087c9d 100644
--- a/src/frame/components/page-footer/SupportSection.module.scss
+++ b/src/frame/components/page-footer/SupportSection.module.scss
@@ -1,6 +1,6 @@
 // The footer help region: feedback, contribution, and support links. This lives in
-// MinimalFooter's `centerComponent` slot, so it supplies its own column chrome —
-// 24px padding and rules — rather than the page container it used to sit in.
+// MinimalFooter's `centerComponent` slot, so it supplies its own column chrome
+// (24px padding and rules) rather than the page container it used to sit in.
 //
 // The design reflows in three stages rather than simply narrowing three columns:
 //
@@ -10,7 +10,7 @@
 //   narrow (<768)  everything stacked, support collapsed into a disclosure
 //
 // MinimalFooter already draws a rule above this whole region, so the first row must
-// not add one — two rules a hair apart read as a mistake. Only rows after the first
+// not add one: two rules a hair apart read as a mistake. Only rows after the first
 // carry a top rule.
 
 $footer-rule: 1px solid
@@ -24,8 +24,8 @@ $footer-rule: 1px solid
 .column {
   // Vertical padding is the design's 24px. The inline inset instead mirrors
   // MinimalFooter's own container padding (20px, 32px from 48rem up), because that
-  // container's padding was dropped for this section so the row rules — which are
-  // column borders — span the footer edge to edge. Keeping the same values here
+  // container's padding was dropped for this section so the row rules, which are
+  // column borders, span the footer edge to edge. Keeping the same values here
   // leaves column content aligned with the top and bottom bars.
   padding-block: var(--base-size-24);
   padding-inline: var(--base-size-20);
@@ -34,7 +34,7 @@ $footer-rule: 1px solid
   color: var(--brand-color-text-default);
 
   // Survey and Contribution each render their own <h3>. The design shows these as
-  // plain body text, not bold headings — restyled here rather than in those
+  // plain body text, not bold headings. Restyled here rather than in those
   // components so they stay free of footer-specific classes. Element selectors also
   // out-specify the Primer utility classes they carry.
   h3 {
@@ -106,14 +106,14 @@ $footer-rule: 1px solid
   }
 
   // A second-row rule only makes sense when there is a first row above it. Any of
-  // these columns can be absent — site-policy and deprecated pages drop the survey,
-  // non-English drops the contribution CTA — and without this gate the surviving
+  // these columns can be absent: site-policy and deprecated pages drop the survey,
+  // non-English drops the contribution CTA. Without this gate the surviving
   // columns would draw a rule directly beneath MinimalFooter's own separator.
   .supportGrid:has(.surveyColumn) .column:not(.surveyColumn) {
     border-top: $footer-rule;
   }
 
-  // Divider between the two columns that share a row — keyed to position rather than
+  // Divider between the two columns that share a row, keyed to position rather than
   // to which component it is, so it lands correctly whichever columns render.
   .column:not(.surveyColumn) + .column {
     border-left: $footer-rule;
diff --git a/src/frame/components/page-footer/SupportSection.tsx b/src/frame/components/page-footer/SupportSection.tsx
index f84de6924f08..282b1ee61972 100644
--- a/src/frame/components/page-footer/SupportSection.tsx
+++ b/src/frame/components/page-footer/SupportSection.tsx
@@ -11,7 +11,7 @@ import { useTranslation } from '@/languages/components/useTranslation'
 import styles from './SupportSection.module.scss'
 
 // Renders inside MinimalFooter's `centerComponent` slot, so it no longer owns a page
-// container or a section heading — the footer supplies that chrome.
+// container or a section heading. The footer supplies that chrome.
 //
 // Columns carry their own class rather than relying on nth-child, because any of the
 // three can be hidden (site-policy pages drop the survey, non-English drops the
diff --git a/src/frame/components/page-header/BreadcrumbsScroller.module.scss b/src/frame/components/page-header/BreadcrumbsScroller.module.scss
index cfee24334cdf..daa100f3a333 100644
--- a/src/frame/components/page-header/BreadcrumbsScroller.module.scss
+++ b/src/frame/components/page-header/BreadcrumbsScroller.module.scss
@@ -14,7 +14,7 @@
 
 // The chevrons overlay the ends of the scroll area (absolutely positioned)
 // rather than sitting in the flex flow. This keeps the scroll area full-width
-// and constant — so its scrollable range never shifts when a chevron toggles —
+// and constant, so its scrollable range never shifts when a chevron toggles,
 // while a hidden chevron leaves NO reserved gap at that edge. Each chevron
 // carries the secondary bar's own background so a crumb scrolling underneath is
 // masked rather than showing through the icon.
@@ -72,11 +72,11 @@
   // Constant 16px on both ends: keeps a crumb off the border at the scroll
   // extremes, and mid-scroll the chevron overlays the end of the trail (its
   // solid background masks whatever passes underneath). Keeping this padding
-  // fixed — never toggled with the chevrons — means the scroll content's width
+  // fixed, never toggled with the chevrons, means the scroll content's width
   // never changes, so toggling a chevron can't reflow the trail or nudge the
   // scroll position (no hop, no mount bounce, no click-lands-short).
   padding: 0 16px;
-  scrollbar-width: none; // Firefox — hide the horizontal scrollbar
+  scrollbar-width: none; // Firefox: hide the horizontal scrollbar
   -ms-overflow-style: none;
 
   &::-webkit-scrollbar {
@@ -85,7 +85,7 @@
 
   // Make the brand Breadcrumbs <nav> the single, full-content-width scroll
   // child. Without this the brand nav fills only the visible width while its
-  // <ol> overflows it — a nested overflow context that freezes scrollLeft at
+  // <ol> overflows it: a nested overflow context that freezes scrollLeft at
   // its max so ancestor crumbs can never be revealed. Growing the nav to
   // max-content removes the nesting so the scroll range spans the whole trail;
   // min-width: 100% keeps short trails left-aligned and filling the container.
diff --git a/src/frame/components/page-header/BreadcrumbsScroller.tsx b/src/frame/components/page-header/BreadcrumbsScroller.tsx
index 655fb5604a33..83754e8cd05f 100644
--- a/src/frame/components/page-header/BreadcrumbsScroller.tsx
+++ b/src/frame/components/page-header/BreadcrumbsScroller.tsx
@@ -14,8 +14,8 @@ import styles from './BreadcrumbsScroller.module.scss'
 const CHEVRON_PAD = 32
 
 // Wraps the secondary-bar breadcrumbs in a horizontal scroll region. When the
-// trail is too long to fit, the region scrolls — anchored to the RIGHT so the
-// current page is shown first — with a left chevron to reveal the leftmost
+// trail is too long to fit, the region scrolls, anchored to the RIGHT so the
+// current page is shown first, with a left chevron to reveal the leftmost
 // (ancestor) crumbs and a right chevron to return to the current page.
 //
 // Accessibility: the underlying <nav aria-label="Breadcrumb"><ol> is untouched,
@@ -39,7 +39,7 @@ export const BreadcrumbsScroller = () => {
   }, [])
 
   // Anchor the trail to its right edge so the current page shows first. Called
-  // on mount and when the available width changes — but NOT on every scroll, so
+  // on mount and when the available width changes, but NOT on every scroll, so
   // it never fights the user (or keyboard focus) scrolling left.
   const anchorRight = useCallback(() => {
     const el = scrollRef.current
@@ -57,7 +57,7 @@ export const BreadcrumbsScroller = () => {
     if (!scroller || typeof ResizeObserver === 'undefined') return
     // Observe the OUTER scroller (not the scroll area). Its width is stable when
     // the chevron shows/hides inside it, so re-anchoring only fires on genuine
-    // layout changes (rail collapse/expand, viewport resize) — not the ~32px
+    // layout changes (rail collapse/expand, viewport resize), not the ~32px
     // shift from the chevron toggling, which would otherwise create a feedback
     // loop that snaps the scroll back to the right the moment you reach the start.
     let lastWidth = scroller.clientWidth
@@ -112,7 +112,7 @@ export const BreadcrumbsScroller = () => {
   // When a crumb link receives focus via keyboard (Tab), the browser does not
   // reliably scroll it into view inside this overflow container (the brand
   // Breadcrumbs nav is itself an overflow context, which confuses
-  // scrollIntoView), so compute and apply the scroll ourselves — otherwise
+  // scrollIntoView), so compute and apply the scroll ourselves. Otherwise
   // keyboard users can focus an off-screen link with no visible focus indicator.
   const handleFocus = useCallback((event: FocusEvent<HTMLDivElement>) => {
     const container = scrollRef.current
@@ -125,10 +125,10 @@ export const BreadcrumbsScroller = () => {
     // Scroll instantly (not smoothly) on focus so the reveal keeps pace with
     // Tab and the focus ring never trails off-screen.
     if (linkRect.left < containerRect.left + pad) {
-      // Off-screen (or clipped) to the left — scroll left to reveal it.
+      // Off-screen (or clipped) to the left, so scroll left to reveal it.
       container.scrollBy({ left: linkRect.left - (containerRect.left + pad), behavior: 'instant' })
     } else if (linkRect.right > containerRect.right - pad) {
-      // Off-screen to the right — scroll right to reveal it.
+      // Off-screen to the right, so scroll right to reveal it.
       container.scrollBy({
         left: linkRect.right - (containerRect.right - pad),
         behavior: 'instant',
@@ -140,8 +140,8 @@ export const BreadcrumbsScroller = () => {
     <div ref={scrollerRef} className={styles.scroller}>
       {/* Both chevrons are always rendered (toggled via visibility) and overlay
           the scroll area's ends rather than sitting beside it, so their
-          show/hide never changes the scroll area's width — which would shift
-          the scrollable range and fight the scroll position — and a hidden
+          show/hide never changes the scroll area's width; changing it would
+          shift the scrollable range and fight the scroll position. A hidden
           chevron leaves no gap at that edge. Hidden chevrons are removed from
           the tab order and the accessibility tree. */}
       <IconButton
diff --git a/src/frame/components/page-header/DocsSecondaryBar.module.scss b/src/frame/components/page-header/DocsSecondaryBar.module.scss
index 068e1eedf4d2..2bfd5df98514 100644
--- a/src/frame/components/page-header/DocsSecondaryBar.module.scss
+++ b/src/frame/components/page-header/DocsSecondaryBar.module.scss
@@ -1,4 +1,4 @@
-// Docs 2026 secondary bar — sits below the main header. On desktop the left
+// Docs 2026 secondary bar: sits below the main header. On desktop the left
 // segment matches the 326px rail width (toggle cell + breadcrumbs) and carries
 // the rail's right divider; a bottom border separates the bar from the content
 // and nav below. On mobile the left segment spans the full width.
diff --git a/src/frame/components/page-header/HeaderNotifications.tsx b/src/frame/components/page-header/HeaderNotifications.tsx
index 35fcef270907..d8fdc06ca6fd 100644
--- a/src/frame/components/page-header/HeaderNotifications.tsx
+++ b/src/frame/components/page-header/HeaderNotifications.tsx
@@ -59,11 +59,9 @@ export const HeaderNotifications = () => {
           try {
             setUserLanguageCookie('en')
           } catch (err) {
-            // You can never be too careful because setting a cookie
-            // can fail. For example, some browser
-            // extensions disallow all setting of cookies and attempts
-            // at the `document.cookie` setter could throw. Just swallow
-            // and move on.
+            // Setting a cookie can fail: some browser extensions disallow it
+            // entirely, and the `document.cookie` setter can throw. Swallow and
+            // move on.
             console.warn('Unable to set cookie', err)
           }
         },
diff --git a/src/frame/components/sidebar/SidebarCollapseContext.tsx b/src/frame/components/sidebar/SidebarCollapseContext.tsx
index 9cff55f217de..7983d994743c 100644
--- a/src/frame/components/sidebar/SidebarCollapseContext.tsx
+++ b/src/frame/components/sidebar/SidebarCollapseContext.tsx
@@ -14,8 +14,8 @@ import { SIDEBAR_COLLAPSED_COOKIE_NAME } from '@/frame/lib/constants'
 //
 // SSR-safety: the cookie is read server-side in getMainContext and passed to the
 // provider as `initialCollapsed`, so the first render (server + client hydration)
-// already reflects the persisted state and markup matches — no flash of the open
-// rail before it collapses. When no initial is supplied, it falls back to reading
+// already reflects the persisted state and markup matches, with no flash of the
+// open rail before it collapses. When no initial is supplied, it falls back to reading
 // the cookie client-side via the SSR-safe cookie lib.
 
 function readCollapsed(): boolean {
@@ -30,7 +30,7 @@ function persistCollapsed(collapsed: boolean) {
   try {
     Cookies.set(SIDEBAR_COLLAPSED_COOKIE_NAME, String(collapsed))
   } catch {
-    // Cookie writes may fail (disabled cookies, etc.) — degrade to non-persisted
+    // Cookie writes may fail (disabled cookies, etc.), so degrade to non-persisted
     // state rather than throwing.
   }
 }
@@ -41,7 +41,7 @@ type SidebarCollapseContextValue = {
   toggleCollapsed: () => void
   setCollapsed: (collapsed: boolean) => void
   // Mobile: whether the doc-tree nav is expanded inline (not persisted). The
-  // nav renders in the page flow, same as desktop — not in a dialog overlay.
+  // nav renders in the page flow, same as desktop, not in a dialog overlay.
   mobileNavOpen: boolean
   toggleMobileNav: () => void
   closeMobileNav: () => void
@@ -86,7 +86,7 @@ export function SidebarCollapseProvider({
 
   // Growing the viewport to the desktop (xxl) layout takes over from the inline
   // mobile nav and hides its toggle, so close the mobile nav when we cross the
-  // breakpoint — otherwise its open state stays stuck and keeps the content
+  // breakpoint. Otherwise its open state stays stuck and keeps the content
   // column hidden. 1400px mirrors breakpoint-xxl.scss.
   useEffect(() => {
     if (typeof window === 'undefined' || !window.matchMedia) return
diff --git a/src/frame/components/sidebar/SidebarNav.module.scss b/src/frame/components/sidebar/SidebarNav.module.scss
index e5abc5d21bdd..27657330fe02 100644
--- a/src/frame/components/sidebar/SidebarNav.module.scss
+++ b/src/frame/components/sidebar/SidebarNav.module.scss
@@ -14,7 +14,7 @@
 // When the mobile nav is expanded inline, the rail spans the full width and
 // flows in the page (no fixed height / sticky) below the xxl breakpoint. At xxl
 // the desktop rail takes over, so revert to the fixed rail width even if the
-// mobile-open state is momentarily still set (e.g. mid-resize) — otherwise the
+// mobile-open state is momentarily still set (e.g. mid-resize). Otherwise the
 // full-width rail covers the article content.
 .sidebarFullMobileOpen {
   width: 100%;
@@ -56,7 +56,7 @@
 // width: below brand's `medium` breakpoint it is a full-width block holding the
 // "Show filters" disclosure, and from `medium` up it becomes the sidebar column.
 //
-// From `medium` up its right divider is the SINGLE border around the filters —
+// From `medium` up its right divider is the SINGLE border around the filters:
 // the panel inside drops its own, so they don't read as a box within a box.
 //
 // It also deliberately does NOT reuse .sidebarFull's sticky offsets. Those assume
@@ -70,7 +70,7 @@
   width: 100%;
 
   // A search with no hits has no facets to offer, so SidebarSearchAggregates renders
-  // nothing — but the column would still reserve its width and draw its divider, leaving
+  // nothing, but the column would still reserve its width and draw its divider, leaving
   // an empty 300px gutter beside the "0 results" message. Collapse it when there is no
   // filter group inside. Browsers without :has() simply keep the old empty column.
   &:not(:has(fieldset)) {
diff --git a/src/frame/components/sidebar/SidebarNav.tsx b/src/frame/components/sidebar/SidebarNav.tsx
index e53a1819a7ff..d6564656c6ec 100644
--- a/src/frame/components/sidebar/SidebarNav.tsx
+++ b/src/frame/components/sidebar/SidebarNav.tsx
@@ -13,7 +13,7 @@ import styles from './SidebarNav.module.scss'
 type Props = {
   variant?: 'full' | 'overlay'
   // When true (full variant only), the rail is also shown on mobile, inline in
-  // the page flow — the Docs 2026 mobile nav expands like the desktop view
+  // the page flow. The Docs 2026 mobile nav expands like the desktop view
   // rather than opening a dialog overlay.
   mobileOpen?: boolean
 }
@@ -30,8 +30,9 @@ export const SidebarNav = ({ variant = 'full', mobileOpen = false }: Props) => {
 
   const isSearch = currentProduct?.id === 'search'
   // `search_results` only ships in the page props on /search, and
-  // createTranslationFunctions warns about a missing namespace at construction — not at
-  // t() call — so asking for it unconditionally would log on every render of every page.
+  // createTranslationFunctions warns about a missing namespace at construction, not
+  // at the t() call, so asking for it unconditionally would log on every render of
+  // every page.
   const { t } = useTranslation(isSearch ? 'search_results' : 'header')
 
   return (
@@ -60,7 +61,7 @@ export const SidebarNav = ({ variant = 'full', mobileOpen = false }: Props) => {
     >
       <nav
         // On search the rail holds the facet filters rather than a doc tree, and the
-        // product-title heading that normally names this nav isn't rendered — so name it
+        // product-title heading that normally names this nav isn't rendered, so name it
         // directly rather than pointing aria-labelledby at an element that isn't there.
         aria-labelledby={isSearch ? undefined : 'allproducts-menu'}
         role="navigation"
diff --git a/src/frame/components/ui/MarkdownContent/UnrenderedMarkdownContent.tsx b/src/frame/components/ui/MarkdownContent/UnrenderedMarkdownContent.tsx
index c2ae7d829eec..5b03961433e4 100644
--- a/src/frame/components/ui/MarkdownContent/UnrenderedMarkdownContent.tsx
+++ b/src/frame/components/ui/MarkdownContent/UnrenderedMarkdownContent.tsx
@@ -38,18 +38,14 @@ export const UnrenderedMarkdownContent = ({
 }: MarkdownContentPropsT) => {
   const { t } = useTranslation('search')
 
-  // Overrides for ReactMarkdown components
   const components = {} as Components
   if (codeBlocksCopyable) {
     // Override the default code block to make multiline code blocks copyable
     components.code = ({ ...props }) => {
-      // get the literal text of the code block
       let text = String(props.children)
-      // If the codeblock is not multiline, return inline code block without copy functionality
       if (!text.includes('\n')) {
         return <code {...props}>{props.children}</code>
       } else {
-        // Otherwise it's multiline and we want to make it copyable
         text = text.replace(/\n$/, '')
       }
 
@@ -62,7 +58,6 @@ export const UnrenderedMarkdownContent = ({
         successDuration: 2000,
       })
 
-      // Create more descriptive aria-label
       const getAriaLabel = () => {
         if (isCopied) {
           return t('search.ai.response.copied_code')
@@ -101,19 +96,16 @@ export const UnrenderedMarkdownContent = ({
   components.a = ({ ...props }) => {
     let href = props.href || ''
     let existingAnchorParams = ''
-    // When we want to include specific query parameters in the URL
     if (includeQueryParams) {
       if (href.includes('?')) {
         href = href.split('?')[0]
         existingAnchorParams = href.split('?')[1]
       }
-      // Include feature, search-overlay-ask-ai, and search-overlay-input query parameters if they exist in the current URL
       const existingURLParams = new URLSearchParams(window.location.search)
       const newParams = new URLSearchParams()
       if (existingURLParams.get('feature')) {
         newParams.set('feature', existingURLParams.get('feature') || '')
       }
-      // Combine new and existing query parameters
       if (newParams.toString()) {
         href = `${href}?${existingAnchorParams}&${newParams.toString()}`
       }
diff --git a/src/frame/components/ui/ScrollButton/ScrollButton.tsx b/src/frame/components/ui/ScrollButton/ScrollButton.tsx
index 0e190ea7383d..8510eebc805d 100644
--- a/src/frame/components/ui/ScrollButton/ScrollButton.tsx
+++ b/src/frame/components/ui/ScrollButton/ScrollButton.tsx
@@ -16,9 +16,8 @@ export const ScrollButton = ({ className, ariaLabel }: ScrollButtonPropsT) => {
   const [isTallEnough, setIsTallEnough] = useState(false)
 
   useEffect(() => {
-    // We cannot determine document.documentElement.scrollTop height because we set the height: 100vh and set overflow to auto to keep the header sticky
-    // That means window.scrollTop height is always 0
-    // Using IntersectionObserver we can determine if the h1 header is in view or not. If not, we show the scroll to top button, if so, we hide it
+    // Show the button once the article h1 has scrolled out of view, and hide it
+    // again when the h1 comes back.
     const h1Element = document.getElementsByTagName('h1')[0]
     if (!h1Element) {
       if (process.env.NODE_ENV !== 'production') {

From 8757a47a65243dc6ae72867269cc859a0230a704 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:19:35 +0000
Subject: [PATCH 09/16] Trim excessive comments in src/frame/lib (#63257)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/frame/lib/constants.ts              |   7 +-
 src/frame/lib/create-tree.ts            |  18 ++--
 src/frame/lib/fetch-utils.ts            | 122 ++++++++++--------------
 src/frame/lib/find-page-in-site-tree.ts |  15 +--
 src/frame/lib/find-page.ts              |   2 -
 src/frame/lib/frontmatter.ts            |   7 +-
 src/frame/lib/get-mini-toc-items.ts     |  13 +--
 src/frame/lib/get-remote-json.ts        |  23 ++---
 src/frame/lib/load-yaml.ts              |   6 +-
 src/frame/lib/page-data.ts              |  37 ++++---
 src/frame/lib/page.ts                   |   9 --
 src/frame/lib/path-utils.ts             |   6 --
 12 files changed, 99 insertions(+), 166 deletions(-)

diff --git a/src/frame/lib/constants.ts b/src/frame/lib/constants.ts
index ae2fddeb40cf..27d089ad9400 100644
--- a/src/frame/lib/constants.ts
+++ b/src/frame/lib/constants.ts
@@ -9,7 +9,7 @@ export const MAX_REQUEST_TIMEOUT = process.env.REQUEST_TIMEOUT
   ? parseInt(process.env.REQUEST_TIMEOUT, 10)
   : DEFAULT_MAX_REQUEST_TIMEOUT
 
-// Docs cookies — we own these and use snake_case naming.
+// Docs cookies. We own these, so they use our snake_case naming.
 export const USER_LANGUAGE_COOKIE_NAME = 'user_language' // Also referenced in Fastly VCL
 export const USER_VERSION_COOKIE_NAME = 'user_version' // Also referenced in Fastly VCL
 export const API_VERSION_COOKIE_NAME = 'api_version_preferred'
@@ -22,14 +22,13 @@ export const MACHINE_TRANSLATION_BANNER_COOKIE_NAME = 'machine_translation_banne
 export const SIDEBAR_EXPANDED_COOKIE_NAME = 'sidebar_expanded'
 export const SIDEBAR_COLLAPSED_COOKIE_NAME = 'sidebar_collapsed'
 
-// Monolith cookies — set by github.com, read-only for us. Names are not
-// ours to change so they don't follow our snake_case convention.
+// Monolith cookies, set by github.com and read-only for us.
+// The names are not ours to change, so they skip our snake_case convention.
 export const COLOR_MODE_COOKIE_NAME = 'color_mode'
 export const PREFERRED_COLOR_MODE_COOKIE_NAME = 'preferred_color_mode'
 export const DOTCOM_USER_COOKIE_NAME = 'dotcom_user'
 export const STAFFONLY_COOKIE_NAME = 'staffonly'
 
-// Feature flags
 export const ANALYTICS_ENABLED = true
 export const HOVERCARDS_ENABLED = true
 
diff --git a/src/frame/lib/create-tree.ts b/src/frame/lib/create-tree.ts
index 270193e2ddb3..b6405cfb0bf9 100644
--- a/src/frame/lib/create-tree.ts
+++ b/src/frame/lib/create-tree.ts
@@ -21,8 +21,8 @@ export default async function createTree(
   let filepath: string
   let mtime: number
   // This kills two birds with one stone. We (attempt to) read it as a file,
-  // to find out if it's a directory or a file and whence we know that
-  // we also collect it's modification time.
+  // to find out if it's a directory or a file, and while we're there we also
+  // collect its modification time.
   try {
     filepath = `${originalPath}.md`
     mtime = await getMtime(filepath)
@@ -44,8 +44,8 @@ export default async function createTree(
       }
       // Throw an error if we can't find a content file associated with the children: entry.
       // But don't throw an error if the user is running the site locally and hasn't cloned the Early Access repo.
-      // Also don't throw for missing children *within* early-access content — a broken
-      // early-access article should not block every docs-internal PR from merging.
+      // Also don't throw for missing children *within* early-access content.
+      // A broken early-access article should not block every docs-internal PR.
       const msg = `Cannot find a content file at ${originalPath}. Check the 'children' frontmatter in the parent index.md.`
 
       if (
@@ -85,7 +85,6 @@ export default async function createTree(
     page = newPage as unknown as Page
   }
 
-  // Create the root tree object on the first run, and create children recursively.
   const item: UnversionedTree = {
     page,
     // This is only here for the sake of reloading the tree later which
@@ -98,12 +97,10 @@ export default async function createTree(
     // this value now will be different from what it was before.
     // It's not enough to rely on *length* of the array before and after
     // because the change could have been to remove one and add another.
-    // Page class has dynamic frontmatter properties like 'children' that aren't in the type definition
     children: page.children || [],
     childPages: [],
   }
 
-  // Process frontmatter children recursively.
   if (page.children) {
     assertUniqueChildren(page)
     item.childPages = (
@@ -122,12 +119,11 @@ export default async function createTree(
             }
           }
 
-          // Handle absolute /content/ paths - allows cross-product directory inclusion
-          // e.g., /content/actions/workflows will include the entire actions/workflows tree
+          // Absolute /content/ paths pull in a whole subtree resolved from the
+          // content root, which may or may not be the current product.
+          // For example, /content/actions/workflows includes all of actions/workflows.
           let childPath: string
           if (child.startsWith('/content/')) {
-            // Absolute content path - resolve from the content root
-            // Strip '/content/' prefix and join with the base content directory
             const absoluteChildPath = child.slice('/content/'.length)
             childPath = path.posix.join(basePath, absoluteChildPath)
 
diff --git a/src/frame/lib/fetch-utils.ts b/src/frame/lib/fetch-utils.ts
index dc50fc2a3e7d..3b82a83f720d 100644
--- a/src/frame/lib/fetch-utils.ts
+++ b/src/frame/lib/fetch-utils.ts
@@ -1,7 +1,4 @@
-/**
- * Utility functions for fetch with retry and timeout functionality
- * to replace got library functionality
- */
+// Fetch with retry and timeout, replacing what we used to get from `got`.
 import statsd from '@/observability/lib/statsd'
 
 const STATSD_FETCH_TIMEOUT = 'fetch.timeout'
@@ -11,33 +8,28 @@ export interface FetchWithRetryOptions {
   retryDelay?: number
   timeout?: number
   throwHttpErrors?: boolean
-  /**
-   * How the `timeout` is enforced:
-   * - 'full' (default): bounds the entire request, including body transfer.
-   *   The abort signal stays armed through body reads, so pair this with
-   *   `readBodyWithTimeout` to report body-phase timeouts consistently.
-   * - 'ttfb': bounds only time-to-first-byte. The timer is cleared once the
-   *   response resolves, leaving body reads unbounded. Use for large, trusted,
-   *   well-cached payloads (e.g. multi-MB archived `redirects.json`) where a
-   *   short deadline should fail fast on an unresponsive server but must not
-   *   abort a legitimately long download.
-   */
+  // How the `timeout` is enforced:
+  //
+  // 'full' (default) bounds the entire request, including body transfer.
+  // The abort signal stays armed through body reads, so pair this with
+  // `readBodyWithTimeout` to report body-phase timeouts consistently.
+  //
+  // 'ttfb' bounds only time-to-first-byte. The timer is cleared once the
+  // response resolves, leaving body reads unbounded. Use it for large, trusted,
+  // well-cached payloads such as the multi-MB archived `redirects.json`, where a
+  // short deadline should fail fast on an unresponsive server but must not abort
+  // a legitimately long download.
   timeoutMode?: 'full' | 'ttfb'
   // Note: Custom HTTPS agents are not supported in native fetch
   // Consider using undici or node-fetch if custom agent support is critical
 }
 
-/**
- * Default retry delay calculation matching got's behavior:
- * sleep = 1000 * Math.pow(2, retry - 1) + Math.random() * 100
- */
+// Matches got's default retry delay:
+// sleep = 1000 * Math.pow(2, retry - 1) + Math.random() * 100
 function calculateDefaultDelay(attempt: number): number {
   return 1000 * Math.pow(2, attempt - 1) + Math.random() * 100
 }
 
-/**
- * Sleep for a given number of milliseconds
- */
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -50,25 +42,21 @@ function getHost(url: string | URL): string {
   }
 }
 
-/**
- * Fetch with timeout support.
- *
- * `timeoutMode` controls what the deadline bounds:
- *
- * - 'full' (default): enforced with `AbortSignal.timeout()`, whose signal
- *   stays armed after this function returns. Callers typically read the body
- *   (`r.json()`, `r.arrayBuffer()`) after the response resolves; because the
- *   signal is never cleared, that body read is aborted by the same deadline.
- *   So the timeout bounds the full request (time-to-first-byte AND body
- *   transfer). Use `readBodyWithTimeout` to consume the body so a body-phase
- *   timeout reports the same way as a TTFB timeout.
- *
- * - 'ttfb': enforced with a manual `AbortController` whose timer is cleared as
- *   soon as the response resolves. Only time-to-first-byte is bounded; the
- *   body read that follows is left unbounded. Use for large, trusted,
- *   well-cached payloads where a short deadline should fail fast on an
- *   unresponsive server but not abort a legitimately long download.
- */
+// `timeoutMode` controls what the deadline bounds.
+//
+// 'full' (default) is enforced with `AbortSignal.timeout()`, whose signal stays
+// armed after this function returns. Callers typically read the body
+// (`r.json()`, `r.arrayBuffer()`) after the response resolves, and because the
+// signal is never cleared, that body read is aborted by the same deadline. So
+// the timeout bounds the full request, both time-to-first-byte AND body
+// transfer. Use `readBodyWithTimeout` to consume the body, so a body-phase
+// timeout reports the same way as a TTFB timeout.
+//
+// 'ttfb' is enforced with a manual `AbortController` whose timer is cleared as
+// soon as the response resolves. Only time-to-first-byte is bounded, and the
+// body read that follows is left unbounded. Use it for large, trusted,
+// well-cached payloads where a short deadline should fail fast on an
+// unresponsive server but not abort a legitimately long download.
 async function fetchWithTimeout(
   url: string | URL,
   init?: RequestInit,
@@ -126,20 +114,14 @@ async function fetchWithTimeout(
   }
 }
 
-/**
- * Read a response body, reporting a timeout the same way `fetchWithTimeout`
- * does for time-to-first-byte.
- *
- * The body read is already bounded by the deadline set on the originating
- * `fetchWithRetry`/`fetchWithTimeout` call (the abort signal stays armed
- * through body transfer). This wrapper just translates the resulting
- * `TimeoutError` into the friendly "Request timed out" error and emits the
- * `fetch.timeout` metric, so body-phase timeouts are observable.
- *
- * @param response The response whose body to read (used for the metric host).
- * @param read A callback that performs the body read, e.g. `() => r.json()`.
- * @param timeout The deadline that bounded the request, for the error message.
- */
+// Reads a response body, reporting a timeout the same way `fetchWithTimeout`
+// does for time-to-first-byte.
+//
+// The body read is already bounded by the deadline set on the originating
+// `fetchWithRetry` or `fetchWithTimeout` call, because the abort signal stays
+// armed through body transfer. This wrapper only translates the resulting
+// `TimeoutError` into the friendly "Request timed out" error and emits the
+// `fetch.timeout` metric, so body-phase timeouts are observable.
 export async function readBodyWithTimeout<T>(
   response: Response,
   read: () => Promise<T>,
@@ -156,9 +138,10 @@ export async function readBodyWithTimeout<T>(
   }
 }
 
-/**
- * Fetch with retry logic matching got's behavior
- */
+// Retries 5xx with an exponential delay modelled on `got`. A 429 also retries,
+// but only when `throwHttpErrors` is on, since otherwise it is returned as-is.
+// The rest of `got`'s retry rules are not reproduced: there is no method
+// allowlist, and 408 and 413 never retry.
 export async function fetchWithRetry(
   url: string | URL,
   init?: RequestInit,
@@ -172,7 +155,6 @@ export async function fetchWithRetry(
     try {
       const response = await fetchWithTimeout(url, init, timeout, timeoutMode)
 
-      // Check if we should retry based on status code
       if (response.status >= 500 && attempt < retries) {
         lastError = new Error(`HTTP ${response.status}: ${response.statusText}`)
         const delay = calculateDefaultDelay(attempt + 1)
@@ -180,7 +162,6 @@ export async function fetchWithRetry(
         continue
       }
 
-      // If throwHttpErrors is true and status indicates an error
       if (throwHttpErrors && !response.ok && response.status >= 400) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`)
       }
@@ -189,12 +170,10 @@ export async function fetchWithRetry(
     } catch (error) {
       lastError = error instanceof Error ? error : new Error(String(error))
 
-      // Don't retry on the last attempt
       if (attempt === retries) {
         throw lastError
       }
 
-      // Don't retry on client errors (4xx) unless it's specific ones
       if (
         error instanceof Error &&
         error.message.includes('HTTP 4') &&
@@ -203,7 +182,6 @@ export async function fetchWithRetry(
         throw lastError
       }
 
-      // Calculate delay and wait before retry
       const delay = calculateDefaultDelay(attempt + 1)
       await sleep(delay)
     }
@@ -212,16 +190,13 @@ export async function fetchWithRetry(
   throw lastError || new Error('Maximum retries exceeded')
 }
 
-/**
- * Create a streaming fetch request that returns a ReadableStream
- * This replaces got.stream functionality
- *
- * Defaults to `timeoutMode: 'ttfb'` because streaming callers consume the body
- * incrementally over a `reader.read()` loop that can legitimately run far longer
- * than the connect deadline. A `'full'` default would keep `AbortSignal.timeout()`
- * armed through that loop and abort a valid long answer mid-stream. Callers that
- * want the deadline to bound the whole transfer can pass `timeoutMode: 'full'`.
- */
+// Replaces got.stream.
+//
+// Defaults to `timeoutMode: 'ttfb'` because streaming callers consume the body
+// incrementally over a `reader.read()` loop that can legitimately run far longer
+// than the connect deadline. A `'full'` default would keep `AbortSignal.timeout()`
+// armed through that loop and abort a valid long answer mid-stream. Callers that
+// want the deadline to bound the whole transfer can pass `timeoutMode: 'full'`.
 export async function fetchStream(
   url: string | URL,
   init?: RequestInit,
@@ -231,7 +206,6 @@ export async function fetchStream(
 
   const response = await fetchWithTimeout(url, init, timeout, timeoutMode)
 
-  // Check for HTTP errors if throwHttpErrors is enabled
   if (throwHttpErrors && !response.ok && response.status >= 400) {
     throw new Error(`HTTP ${response.status}: ${response.statusText}`)
   }
diff --git a/src/frame/lib/find-page-in-site-tree.ts b/src/frame/lib/find-page-in-site-tree.ts
index f97565ae52c2..3df91d1fbc6c 100644
--- a/src/frame/lib/find-page-in-site-tree.ts
+++ b/src/frame/lib/find-page-in-site-tree.ts
@@ -1,8 +1,6 @@
 import type { Tree } from '@/types'
 import { getLanguageCode } from './patterns'
 
-// This module recursively searches a given part of the site tree by iterating through child
-// pages and finding a path that matches the original path provided.
 export default function findPageInSiteTree(
   treePage: Tree,
   englishTree: Tree,
@@ -11,32 +9,25 @@ export default function findPageInSiteTree(
 ): Tree {
   if (Array.isArray(treePage)) throw new Error('received array instead of object')
 
-  // If the tree page already matches the path, or if it has no child pages, return the page itself.
   if (treePage.href === originalPath || !treePage.childPages) {
     return treePage
   }
 
-  // If no modified path is provided, set it to the original path.
   if (!modifiedPath) {
     modifiedPath = originalPath
   }
 
-  // Find the index of the modified path in the array of child pages.
   const foundIndex = treePage.childPages.findIndex(({ href }) => href === modifiedPath)
 
-  // Use that index to find the child page that matches the path.
   const foundPage = treePage.childPages[foundIndex]
 
-  // If we found a page...
   if (foundPage) {
     return modifiedPath === originalPath
-      ? // Check if it matches the _original_ path, and return it if so.
-        foundPage
-      : // If we found a page with the modified path, keep going down the tree until we find the original path.
-        findPageInSiteTree(foundPage, englishTree, originalPath)
+      ? foundPage
+      : findPageInSiteTree(foundPage, englishTree, originalPath)
   }
 
-  // If no page was found at the path we tried, try again by removing the last segment of the path.
+  // Try again with the last path segment removed.
   modifiedPath = modifiedPath.replace(/\/[^/]+?$/, '')
 
   // Error out or we'll just recurse forever until the stack size is exceeded.
diff --git a/src/frame/lib/find-page.ts b/src/frame/lib/find-page.ts
index 1514f7604209..664a3a396c5b 100644
--- a/src/frame/lib/find-page.ts
+++ b/src/frame/lib/find-page.ts
@@ -15,12 +15,10 @@ export default function findPage(
 
   const redirectsContext: Context = { redirects: redirects || {}, pages }
 
-  // find the page
   const redirectedHref = getRedirect(href, redirectsContext)
   const page = pages[href] || (redirectedHref ? pages[redirectedHref] : undefined)
   if (page) return page
 
-  // get the current language
   const languageMatch = href.match(getLanguageCode)
   const currentLang = getLanguageCode.test(href) && languageMatch ? languageMatch[1] : 'en'
 
diff --git a/src/frame/lib/frontmatter.ts b/src/frame/lib/frontmatter.ts
index 6abc6f1d8777..ce68dc51b0c5 100644
--- a/src/frame/lib/frontmatter.ts
+++ b/src/frame/lib/frontmatter.ts
@@ -286,8 +286,8 @@ export const schema: Schema = {
       type: 'string',
       enum: ['mac', 'windows', 'linux'],
     },
-    // Tool-specific content preference, the list of tools are kept in
-    // make it easier to update in a single place
+    // Tool-specific content preference.
+    // The tool list lives in allTools so it only has to be updated in one place.
     defaultTool: {
       type: 'string',
       enum: Object.keys(allTools),
@@ -353,7 +353,6 @@ export const schema: Schema = {
         'webhooks',
       ],
     },
-    // START category-landing tags
     category: {
       type: 'array',
       errorMessage: `must be an array, which is written in frontmatter like:
@@ -372,7 +371,6 @@ category:
     octicon: {
       type: 'string',
     },
-    // END category landing tags
     // Custom sidebar link for category pages
     sidebarLink: {
       type: 'object',
@@ -444,7 +442,6 @@ category:
   },
 }
 
-// returns a list of deprecated properties
 export const deprecatedProperties = Object.keys(schema.properties).filter((prop: string) => {
   return (schema.properties as Record<string, SchemaProperty>)[prop].deprecated
 })
diff --git a/src/frame/lib/get-mini-toc-items.ts b/src/frame/lib/get-mini-toc-items.ts
index 7949a4955d34..37a6b4cc8098 100644
--- a/src/frame/lib/get-mini-toc-items.ts
+++ b/src/frame/lib/get-mini-toc-items.ts
@@ -27,11 +27,11 @@ interface FlatTocItem {
   items?: FlatTocItem[]
 }
 
-// Build MiniTocItems from pre-collected heading data (from the collect-mini-toc
-// rehype plugin). This is the only path for generating mini-TOC items — headings
-// are collected directly from the AST during rendering, avoiding any HTML
-// re-parsing.
-// Keep maxHeadingLevel=2 for accessibility reasons, see docs-engineering#2701
+// Builds MiniTocItems from heading data the collect-mini-toc rehype plugin
+// gathered. This is the only path, because headings come straight off the AST
+// during rendering and never get re-parsed out of HTML.
+//
+// Keep maxHeadingLevel=2 for accessibility reasons. See docs-engineering#2701.
 export function buildMiniTocFromCollected(
   collected: CollectedHeading[],
   maxHeadingLevel = 2,
@@ -62,7 +62,6 @@ export function buildMiniTocFromCollected(
   return minimalMiniToc(nestedToc)
 }
 
-// Recursively build a tree from the list of allItems
 function buildNestedToc(allItems: FlatTocItem[], startIndex = 0): FlatTocItem[] {
   const startItem = allItems[startIndex]
   if (!startItem) {
@@ -76,7 +75,6 @@ function buildNestedToc(allItems: FlatTocItem[], startIndex = 0): FlatTocItem[]
     const nextItem = allItems[cursor + 1]
     const nextItemIsNested = nextItem && nextItem.indentationLevel! > cursorItem.indentationLevel!
 
-    // if it's the current indentation level, push it on and keep going
     if (curLevelIndentation === cursorItem.indentationLevel) {
       currentLevel.push({
         ...cursorItem,
@@ -90,7 +88,6 @@ function buildNestedToc(allItems: FlatTocItem[], startIndex = 0): FlatTocItem[]
       continue
     }
 
-    // current root indentation is _greater_ than our current cursor item,
     if (curLevelIndentation > cursorItem.indentationLevel) {
       // special scenario where the initial list started with "less important" headers
       // so we need to reset our expectations of what level to judge the indentation on
diff --git a/src/frame/lib/get-remote-json.ts b/src/frame/lib/get-remote-json.ts
index 857ac42b36d9..9ca918c90e3f 100644
--- a/src/frame/lib/get-remote-json.ts
+++ b/src/frame/lib/get-remote-json.ts
@@ -33,23 +33,25 @@ function decompressFromCache(cacheKey: string): unknown {
   return JSON.parse(zlib.inflateSync(compressed).toString())
 }
 
-// Wrapper on `got()` that is able to both cache in memory and on disk.
-// The on-disk caching is in `.remotejson/`.
-// We use this for downloading `redirects.json` files from one of the
-// docs-ghes-<release number> repos as a proxy. A lot of those
-// .json files are large and they're also static which makes them
-// ideal for caching.
-// Note that there's 2 layers of caching here:
-//  1. Is it in memory cache?
+// Fetches JSON through an in-memory cache and an on-disk cache in
+// `.remotejson-cache/`. The disk cache is read everywhere but only written
+// outside production, so production runs on a prewarmed directory.
+//
+// We use this to download `redirects.json` files from the
+// docs-ghes-<release number> repos. Those files are large and static, which
+// makes them ideal for caching.
+//
+// The lookup order is:
+//  1. Is it in the memory cache?
 //  2. No, is it on disk?
-//  3. No, download from the internet then store responses in memory and disk
+//  3. No, download it, store it in memory, and store it on disk if not in production.
 export default async function getRemoteJSON(
   url: string,
   config?: GetRemoteJSONConfig,
 ): Promise<unknown> {
   // We could get fancy and make the cache key depend on the `config` too
   // given that this is A) only used for archived enterprise stuff,
-  // and B) the config is only applicable on cache miss when doing the `got()`.
+  // and B) the config only applies on a cache miss, when we actually fetch.
   const cacheKey = url
 
   // Assume it's in the in-memory cache first.
@@ -128,7 +130,6 @@ export default async function getRemoteJSON(
       }
 
       const body = await res.text()
-      // Validate JSON, then compress raw string directly
       JSON.parse(body)
       compressStringToCache(cacheKey, body)
 
diff --git a/src/frame/lib/load-yaml.ts b/src/frame/lib/load-yaml.ts
index 44f17e0f11e9..0b0e0d8f8528 100644
--- a/src/frame/lib/load-yaml.ts
+++ b/src/frame/lib/load-yaml.ts
@@ -1,14 +1,14 @@
 import { load, loadAll, type LoadOptions } from 'js-yaml'
 
 // js-yaml v5's `load()` throws a `YAMLException` ("expected a document, but
-// the input is empty") when the input contains no YAML document — i.e. when
-// it is empty, whitespace-only, or comments-only. js-yaml v4 returned
+// the input is empty") when the input contains no YAML document, meaning it is
+// empty, whitespace-only, or comments-only. js-yaml v4 returned
 // `undefined` in those cases. This wrapper restores the v4 behavior so callers
 // that read arbitrary (possibly empty) YAML files keep working across the
 // major version bump.
 //
 // For any input that does contain a document, this behaves exactly like
-// `load()` — including throwing on genuinely malformed YAML.
+// `load()`, including throwing on genuinely malformed YAML.
 export function loadYaml(content: string, options?: LoadOptions): unknown {
   // `loadAll` invokes the iterator once per document and, unlike `load`, does
   // not throw when there are zero documents. Collect the documents so we can
diff --git a/src/frame/lib/page-data.ts b/src/frame/lib/page-data.ts
index 4d23884281c5..d7d63755197a 100644
--- a/src/frame/lib/page-data.ts
+++ b/src/frame/lib/page-data.ts
@@ -160,7 +160,6 @@ async function translateTree(
     }
 
     const read = await readFileContents(fullPath)
-    // If it worked, great!
     content = read.content
     data = read.data as Record<string, unknown>
 
@@ -225,7 +224,7 @@ async function translateTree(
           ? `Unable to parse YAML frontmatter in ${fullPath}, falling back to English. Details: ${error.message}`
           : `Unable to initialize ${fullPath} because translation content file does not exist.`
       if (error instanceof FrontmatterParsingError && error.isYmlError) {
-        // YAML parse failures are always logged — they indicate a translation file is corrupt
+        // Always log YAML parse failures. They mean a translation file is corrupt
         // and will silently serve English until the translation repo is fixed.
         logger.warn(message, { path: relativePath })
       } else if (DEBUG_TRANSLATION_FALLBACKS) {
@@ -299,7 +298,6 @@ async function translateTree(
     ) as unknown as ConstructorParameters<typeof Page>[0],
   ) as unknown as UnversionedTree['page']
 
-  // Preserve the crossProductChild flag from the English tree
   if (enTree.crossProductChild) {
     ;(item as UnversionedTree).crossProductChild = true
   }
@@ -321,18 +319,20 @@ async function translateTree(
   return item as UnversionedTree
 }
 
-/**
- * The siteTree is a nested object with pages for every language and version, useful for nav because it
- * contains parent, child, and sibling relationships:
- *
- * siteTree[languageCode][version].childPages[<array of pages>].childPages[<array of pages>] (etc...)
-
-* Given an unversioned tree of all pages per language, we can walk it for each version and do a couple operations:
- * 1. Add a versioned href to every item, where the href is the relevant permalink for the current version.
- * 2. Drop any child pages that are not available in the current version.
- *
- * Order of languages and versions doesn't matter, but order of child page arrays DOES matter (for navigation).
-*/
+// The siteTree is a nested object with pages for every language and version.
+// It is useful for nav because it carries parent, child, and sibling
+// relationships:
+//
+//    siteTree[languageCode][version].childPages[].childPages[] (etc...)
+//
+// Given an unversioned tree of all pages per language, we walk it once per
+// version and do two things:
+//
+//    1. Add a versioned href to every item, the permalink for that version.
+//    2. Drop any child pages not available in that version.
+//
+// Order of languages and versions doesn't matter, but order of child page
+// arrays DOES matter, because navigation reads it.
 export async function loadSiteTree(
   unversionedTree?: UnversionLanguageTree,
   languagesOnly: string[] = [],
@@ -341,17 +341,14 @@ export async function loadSiteTree(
   const siteTree: SiteTree = {}
 
   const langCodes = (languagesOnly.length && languagesOnly) || Object.keys(languages)
-  // For every language...
   await Promise.all(
     langCodes.map(async (langCode) => {
       if (!(langCode in rawTree)) {
         throw new Error(`No tree for language ${langCode}`)
       }
       const treePerVersion: { [version: string]: Tree } = {}
-      // in every version...
       await Promise.all(
         versions.map(async (version) => {
-          // "version" the pages.
           treePerVersion[version] = await versionPages(
             Object.assign({}, rawTree[langCode]),
             version,
@@ -389,9 +386,7 @@ export async function versionPages(
   if (!tree.childPages) return tree
   const versionedChildPages = await Promise.all(
     tree.childPages
-      // Drop child pages that do not apply to the current version
       .filter((childPage) => childPage.page.applicableVersions.includes(version))
-      // Version the child pages recursively.
       .map((childPage) =>
         versionPages(Object.assign({}, childPage) as unknown as UnversionedTree, version, langCode),
       ),
@@ -432,7 +427,7 @@ export async function loadPageList(
       item.childPages
         // Cross-product children are pages included from other parts of the
         // tree via absolute `/content/` paths in a bespoke landing page's
-        // children list.  They already exist in their original location, so
+        // children list. They already exist in their original location, so
         // including them again would create duplicate entries in the flat
         // page list which breaks search-index uniqueness constraints.
         .filter((childPage: UnversionedTree) => !childPage.crossProductChild)
diff --git a/src/frame/lib/page.ts b/src/frame/lib/page.ts
index 24fffb7b20d5..b8b9efc8ac0e 100644
--- a/src/frame/lib/page.ts
+++ b/src/frame/lib/page.ts
@@ -121,7 +121,6 @@ class Page {
   public allToolsParsed: typeof allTools = allTools
   public introPlainText?: string
 
-  // Bound method
   public render: (context: Context) => Promise<string>
 
   static async init(opts: PageInitOptions): Promise<Page | undefined> {
@@ -212,7 +211,6 @@ class Page {
       )
     }
 
-    // Remove frontmatter errors before assignment
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const { frontmatterErrors: _, ...cleanOpts } = opts
     Object.assign(this, cleanOpts)
@@ -229,7 +227,6 @@ class Page {
     // Is this the Homepage or a Product, Category, Topic, or Article?
     this.documentType = getDocumentType(this.relativePath)
 
-    // Get array of versions that the page is available in for fast lookup
     this.applicableVersions = getApplicableVersions(this.versions, this.fullPath)
 
     // Only check the parent product ID for English because if a top-level
@@ -251,7 +248,6 @@ class Page {
       }
     }
 
-    // derive array of Permalink objects
     this.permalinks = Permalink.derive(
       this.languageCode,
       this.relativePath,
@@ -268,7 +264,6 @@ class Page {
       }
     }
 
-    // if this is an article and it doesn't have showMiniToc = false, set mini TOC to true
     if (!this.relativePath.endsWith('index.md')) {
       this.showMiniToc = this.showMiniToc === false ? this.showMiniToc : true
     }
@@ -285,7 +280,6 @@ class Page {
     >
   }
 
-  // Infer the parent product ID from the page's relative file path
   get parentProductId(): string | null {
     // Each page's top-level content directory matches its product ID
     const id = this.relativePath.split('/')[0]
@@ -293,7 +287,6 @@ class Page {
     // ignore top-level content/index.md
     if (id === 'index.md') return null
 
-    // make sure the ID is valid
     if (process.env.NODE_ENV !== 'test') {
       assert(productMapKeysAsSet.has(id), `page ${this.fullPath} has an invalid product ID: ${id}`)
     }
@@ -322,7 +315,6 @@ class Page {
       context.englishHeadings = englishHeadings
     }
 
-    // pull translations for alerts
     context.alertTitles = await getAlertTitles(this)
 
     this.intro = await renderContentWithFallback(this, 'rawIntro', context)
@@ -420,7 +412,6 @@ class Page {
 
     if (!opts.unwrap) return html
 
-    // The unwrap option removes surrounding tags from a string, preserving any inner HTML
     return stripOuterTag(html)
   }
 
diff --git a/src/frame/lib/path-utils.ts b/src/frame/lib/path-utils.ts
index ff6f1d181c82..542fbab1263e 100644
--- a/src/frame/lib/path-utils.ts
+++ b/src/frame/lib/path-utils.ts
@@ -33,7 +33,6 @@ export function getPathWithoutLanguage(href: string | undefined): string {
   return slash(href.replace(patterns.hasLanguageCode, '/'))
 }
 
-// Remove the version segment from the path
 export function getPathWithoutVersion(href: string | undefined): string {
   if (!href) return '/'
   const versionFromPath = getVersionStringFromPath(href)
@@ -44,7 +43,6 @@ export function getPathWithoutVersion(href: string | undefined): string {
     : href
 }
 
-// Return the version segment in a path
 export function getVersionStringFromPath(
   href: string | undefined,
   supportedOnly: true,
@@ -63,7 +61,6 @@ export function getVersionStringFromPath(
     return nonEnterpriseDefaultVersion
   }
 
-  // Get the first segment
   const versionFromPath = href.split('/')[1]
 
   // If the first segment is a supported product, assume this is FPT
@@ -102,15 +99,12 @@ export function getVersionStringFromPath(
   return versionFromPath
 }
 
-// Return the corresponding object for the version segment in a path
 export function getVersionObjectFromPath(href: string | undefined) {
   const versionFromPath = getVersionStringFromPath(href, false)
 
   return allVersions[versionFromPath]
 }
 
-// Return the product segment from the path
-// Extracts the product identifier from various URL patterns including versioned paths
 export function getProductStringFromPath(href: string | undefined): string {
   // Handle empty or undefined paths
   if (!href) return 'homepage'

From 91644b1ab2c092f36a050158a21fb6c4526a1b07 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:19:41 +0000
Subject: [PATCH 10/16] Trim redundant comments in tools, archives, versions,
 tests, and audit-logs (#63252)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 .../archived-enterprise-versions.ts           | 18 +++----
 src/audit-logs/lib/deduplicate.ts             |  1 -
 src/audit-logs/lib/index.ts                   | 27 ++--------
 src/audit-logs/scripts/rebuild-dedup.ts       | 24 +++++----
 src/audit-logs/scripts/sync.ts                | 14 ++----
 src/tests/helpers/caching-headers.ts          |  1 -
 src/tests/helpers/e2etest.ts                  | 49 -------------------
 src/tests/lib/validate-json-schema.ts         |  2 -
 src/tests/mocks/cse-copilot-mock.ts           | 14 ++----
 src/tests/mocks/start-mock-server.ts          |  8 ---
 src/tools/components/InArticlePicker.tsx      |  2 +-
 src/tools/components/PlatformPicker.tsx       |  2 +-
 src/tools/components/ToolPicker.tsx           |  9 ++--
 src/tools/lib/all-platforms.ts                |  7 +--
 src/tools/lib/all-tools.ts                    |  4 +-
 .../scripts/liquid-markdown-tables/convert.ts |  4 +-
 .../scripts/liquid-markdown-tables/index.ts   |  1 -
 .../scripts/liquid-markdown-tables/lib.ts     |  1 -
 src/versions/lib/all-versions.ts              |  4 +-
 .../lib/enterprise-server-releases.d.ts       | 20 --------
 .../lib/enterprise-server-releases.ts         | 37 ++------------
 src/versions/lib/get-applicable-versions.ts   |  4 --
 22 files changed, 39 insertions(+), 214 deletions(-)

diff --git a/src/archives/middleware/archived-enterprise-versions.ts b/src/archives/middleware/archived-enterprise-versions.ts
index d7501fb082e8..6a678383e7c8 100644
--- a/src/archives/middleware/archived-enterprise-versions.ts
+++ b/src/archives/middleware/archived-enterprise-versions.ts
@@ -105,7 +105,6 @@ export default async function archivedEnterpriseVersions(
   const { isArchived, requestedVersion } = isArchivedVersion(req)
   if (!isArchived || !requestedVersion) return next()
 
-  // Skip asset paths
   if (patterns.assetPaths.test(req.path)) return next()
 
   const redirectCode = pathLanguagePrefixed(req.path) ? 301 : 302
@@ -176,8 +175,6 @@ export default async function archivedEnterpriseVersions(
     // URLs like this only need to redirect the original `req.path`
     // didn't already have a language
     if (newPath !== undefined && (newPath || !language)) {
-      // Construct the new URL by combining the new language and the
-      // new destination.
       const redirect = `/${language || 'en'}${newPath || withoutLanguagePath}`
       cacheAggressively(res)
       return res.safeRedirect(redirectCode, redirect)
@@ -258,8 +255,6 @@ export default async function archivedEnterpriseVersions(
   ])()
   const responseTime = Date.now() - startTime
 
-  // Log warnings for slow responses to help identify degraded performance
-  // A response time over half the timeout indicates potential issues
   if (responseTime > WARN_RESPONSE_THRESHOLD) {
     logger.warn('Slow response from archived enterprise content', {
       version: requestedVersion,
@@ -270,14 +265,14 @@ export default async function archivedEnterpriseVersions(
     })
   }
 
-  // Log non-200 responses — use warn for 404s (expected for missing archived
-  // pages) and error for genuine upstream failures (5xx, timeouts).
+  // Warn on 404s, which are expected for missing archived pages.
+  // Everything else is a genuine upstream failure.
   if (r.status !== 200) {
     let upstreamBody: string | undefined
     try {
       upstreamBody = await readBodyWithTimeout(r, () => r.text(), timeoutConfiguration.response)
     } catch {
-      // ignore — body reading failure shouldn't affect error handling
+      // A body we cannot read should not change how we handle the error.
     }
     const level = r.status === 404 ? 'warn' : 'error'
     logger[level]('Failed to fetch archived enterprise content', {
@@ -369,7 +364,6 @@ export default async function archivedEnterpriseVersions(
         )
       }
 
-      // Continue with remaining replacements
       modifiedBody = modifiedBody.replaceAll(
         /="(\.\.\/)*assets/g,
         `="${ENTERPRISE_GH_PAGES_URL_PREFIX}${requestedVersion}/assets`,
@@ -465,7 +459,7 @@ function getProxyPath(reqPath: string, requestedVersion: string) {
 }
 
 // Module-level global cache object.
-// Get's populated lazily inside getFallbackRedirect().
+// Gets populated lazily inside getFallbackRedirect().
 const fallbackRedirectLookups = new Map()
 
 function getFallbackRedirect(req: ExtendedRequest) {
@@ -543,8 +537,8 @@ function getEarlyNotFoundReason(reqPath: string, version: string): string | null
     return 'double-slash'
   }
 
-  // Duplicated "/developer/developer/" segment — these are broken
-  // crawler URLs from the old developer.github.com site.
+  // A duplicated "/developer/developer/" segment means a broken crawler URL
+  // from the old developer.github.com site.
   if (reqPath.includes('/developer/developer/')) {
     return 'developer-developer'
   }
diff --git a/src/audit-logs/lib/deduplicate.ts b/src/audit-logs/lib/deduplicate.ts
index 39411f47df76..f637fddb4a28 100644
--- a/src/audit-logs/lib/deduplicate.ts
+++ b/src/audit-logs/lib/deduplicate.ts
@@ -77,7 +77,6 @@ export async function writeDeduplicatedAuditLogData(
     }
   }
 
-  // Write shared files
   const sharedDir = path.join(AUDIT_LOG_DATA_DIR, 'shared')
   if (!existsSync(sharedDir)) {
     await mkdirp(sharedDir)
diff --git a/src/audit-logs/lib/index.ts b/src/audit-logs/lib/index.ts
index 4a5bcfcde5d4..4da4d9e11cd3 100644
--- a/src/audit-logs/lib/index.ts
+++ b/src/audit-logs/lib/index.ts
@@ -19,11 +19,10 @@ import config from './config.json'
 
 export const AUDIT_LOG_DATA_DIR = 'src/audit-logs/data'
 
-// cache of audit log data
 const auditLogEventsCache = new Map<string, Map<string, AuditLogEventT[]>>()
 const categorizedAuditLogEventsCache = new Map<string, Map<string, CategorizedEvents>>()
 
-// Shared dedup data — loaded once, shared across all versions
+// Shared dedup data, loaded once and shared across all versions.
 let sharedEntries: DeduplicatedAuditLogEntry[] | null = null
 let sharedFieldsPool: string[][] | null = null
 let sharedVersionIndex: AuditLogVersionIndex | null = null
@@ -58,10 +57,10 @@ function loadSharedFormat(): boolean {
     sharedFormatAvailable = true
   } catch (err) {
     if (isFileNotFoundError(err)) {
-      // Shared files don't exist — fall back to per-version files silently.
+      // Shared files don't exist, so fall back to per-version files silently.
       sharedFormatAvailable = false
     } else {
-      // Corrupt JSON, schema mismatch, etc. — surface this instead of hiding it.
+      // Corrupt JSON, schema mismatch, and so on. Surface it instead of hiding it.
       console.error('Failed to load shared audit log dedup format (corrupt data?):', err)
       throw err
     }
@@ -108,7 +107,6 @@ type PipelineConfig = {
   appendedDescriptions: Record<string, string>
 }
 
-// get category notes from config
 export function getCategoryNotes(): CategoryNotes {
   const auditLogConfig = config as AuditLogConfig
   return auditLogConfig.categoryNotes || {}
@@ -126,7 +124,6 @@ export type TitleResolutionContext = Context & {
 // request (~90–150ms of repeated work). See docs-engineering#6650.
 const referenceLinksMarkdownCache = new Map<string, Promise<string>>()
 
-// Resolves docs_reference_links URLs to markdown links
 export function resolveReferenceLinksToMarkdown(
   docsReferenceLinks: string,
   context: TitleResolutionContext,
@@ -147,7 +144,6 @@ async function computeReferenceLinksToMarkdown(
   docsReferenceLinks: string,
   context: TitleResolutionContext,
 ): Promise<string> {
-  // Handle multiple comma-separated or space-separated links
   const links = docsReferenceLinks
     .split(/[,\s]+/)
     .map((link) => link.trim())
@@ -188,7 +184,6 @@ async function computeReferenceLinksToMarkdown(
   return markdownLinks.join(', ')
 }
 
-// Resolves docs_reference_links URLs to page titles
 async function resolveReferenceLinksToTitles(
   docsReferenceLinks: string,
   context: TitleResolutionContext,
@@ -197,7 +192,6 @@ async function resolveReferenceLinksToTitles(
     return ''
   }
 
-  // Handle multiple comma-separated or space-separated links
   const links = docsReferenceLinks
     .split(/[,\s]+/)
     .map((link) => link.trim())
@@ -258,7 +252,6 @@ export function getAuditLogEvents(page: string, version: string): AuditLogEventT
     auditLogEventsCache.set(openApiVersion, new Map())
   }
   if (!auditLogEventsCache.get(openApiVersion)?.has(page)) {
-    // Try shared deduplicated format first
     const events = reconstructEventsFromSharedFormat(openApiVersion, page)
     if (events) {
       auditLogEventsCache.get(openApiVersion)?.set(page, events)
@@ -307,7 +300,6 @@ export function getCategorizedAuditLogEvents(page: string, version: string): Cat
   return categorizedAuditLogEventsCache.get(openApiVersion)?.get(page) || {}
 }
 
-// Filters audit log events based on allowlist values.
 export async function filterByAllowlistValues({
   eventsToCheck,
   allowListValues,
@@ -337,7 +329,6 @@ export async function filterByAllowlistValues({
       if (seen.has(event.action)) continue
       seen.add(event.action)
 
-      // Merge global fields with event-specific fields
       const mergedFields = event.fields
         ? [...new Set([...globalFields, ...event.fields])]
         : globalFields.length > 0
@@ -351,7 +342,6 @@ export async function filterByAllowlistValues({
         fields: mergedFields,
       }
 
-      // Resolve reference link titles if context is provided
       if (titleContext && event.docs_reference_links && event.docs_reference_links !== 'N/A') {
         try {
           minimal.docs_reference_titles = await resolveReferenceLinksToTitles(
@@ -375,13 +365,6 @@ export async function filterByAllowlistValues({
 // Filters audit log events based on allowlist values and processes an
 // event's supported GHES versions.
 //
-// * eventsToCheck: events to consider
-// * allowListvalue: allowlist value to filter by
-// * currentEvents: events already collected
-// * pipelineConfig: audit log pipeline config data
-// * auditLogPage: the audit log page the event belongs to
-// * titleContext: optional context for resolving reference link titles
-//
 // Mutates `currentGhesEvents` and updates it with any new filtered for audit
 // log events, the object maps GHES versions to page events for that version e.g.:
 //
@@ -442,10 +425,8 @@ export async function filterAndUpdateGhesDataByAllowlistValues({
       if (seenByGhesVersion.get(fullGhesVersion)?.has(event.action)) continue
 
       if (ghesVersionAllowlists.includes(allowListValue)) {
-        // Get event-specific fields (prefer GHES version fields, fall back to base fields)
         const eventFields = event.ghes[ghesVersion].fields || event.fields
 
-        // Merge global fields with event-specific fields
         const mergedFields = eventFields
           ? [...new Set([...globalFields, ...eventFields])]
           : globalFields.length > 0
@@ -459,7 +440,6 @@ export async function filterAndUpdateGhesDataByAllowlistValues({
           fields: mergedFields,
         }
 
-        // Resolve reference link titles if context is provided
         if (titleContext && event.docs_reference_links && event.docs_reference_links !== 'N/A') {
           try {
             minimal.docs_reference_titles = await resolveReferenceLinksToTitles(
@@ -501,7 +481,6 @@ export async function filterAndUpdateGhesDataByAllowlistValues({
   }
 }
 
-// Categorizes the given array of audit log events by event category
 function categorizeEvents(events: AuditLogEventT[]) {
   const categorizedEvents: CategorizedEvents = {}
   for (const event of events) {
diff --git a/src/audit-logs/scripts/rebuild-dedup.ts b/src/audit-logs/scripts/rebuild-dedup.ts
index e369478ac057..32daff1c6ef4 100644
--- a/src/audit-logs/scripts/rebuild-dedup.ts
+++ b/src/audit-logs/scripts/rebuild-dedup.ts
@@ -1,16 +1,14 @@
-/**
- * Rebuilds the deduplicated "shared" audit log format
- * (src/audit-logs/data/shared/entries.json, fields-pool.json, and
- * version-index.json) from the per-version page files already on disk.
- *
- * Unlike `sync-audit-log`, this does NOT fetch from github/audit-log-allowlists
- * and needs no GITHUB_TOKEN. Use it to regenerate the shared files when the
- * per-version JSON files have changed but the shared files are stale (for
- * example, an older audit-log-pipeline PR that predates the dedup format), which
- * makes the `deduplication` test fail.
- *
- *   npm run rebuild-audit-log-dedup
- */
+// Rebuilds the deduplicated "shared" audit log format from the per-version page
+// files already on disk: src/audit-logs/data/shared/entries.json and
+// fields-pool.json, plus src/audit-logs/data/version-index.json.
+//
+// Unlike `sync-audit-log`, this does NOT fetch from github/audit-log-allowlists
+// and needs no GITHUB_TOKEN. Use it to regenerate the shared files when the
+// per-version JSON files have changed but the shared files are stale, for
+// example on an older audit-log-pipeline PR that predates the dedup format.
+// That is what makes the `deduplication` test fail.
+//
+//   npm run rebuild-audit-log-dedup
 import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
 import path from 'path'
 
diff --git a/src/audit-logs/scripts/sync.ts b/src/audit-logs/scripts/sync.ts
index e46b83565ee6..1718d90416a4 100755
--- a/src/audit-logs/scripts/sync.ts
+++ b/src/audit-logs/scripts/sync.ts
@@ -1,12 +1,7 @@
-/**
- * Required env variables:
- *
- * GITHUB_TOKEN
- *
- * Gets latest audit log event data, extracts the data we need for rendering on
- * the 3 different audit log pages, and writes out the data to files versioned
- * per page.
- */
+// Gets the latest audit log event data, extracts what we need for the 3 audit
+// log pages, and writes it out to files versioned per page.
+//
+// Requires GITHUB_TOKEN.
 import { existsSync } from 'fs'
 import { readFile, writeFile } from 'fs/promises'
 import { mkdirp } from 'mkdirp'
@@ -72,7 +67,6 @@ async function main() {
   pipelineConfig.sha = mainSha
   await writeFile(configFilepath, JSON.stringify(pipelineConfig, null, 2))
 
-  // Load pages and redirects for title resolution
   console.log('Loading pages and redirects for title resolution...')
   const pageList = await loadPages(undefined, ['en'])
   const pages = await loadPageMap(pageList)
diff --git a/src/tests/helpers/caching-headers.ts b/src/tests/helpers/caching-headers.ts
index fb3314b3a02c..a8fc1bcf7fd1 100644
--- a/src/tests/helpers/caching-headers.ts
+++ b/src/tests/helpers/caching-headers.ts
@@ -26,7 +26,6 @@ export function checkCachingHeaders(
   // that it's a reasonably large number of seconds.
   expect(maxAgeSeconds).toBeGreaterThanOrEqual(minMaxAge)
 
-  // Because it doesn't have a unique URL
   const surrogateKeyHeader = res.headers['surrogate-key'] as string
   const firstToken = surrogateKeyHeader.split(/\s/g)[0]
   if (defaultSurrogateKey) {
diff --git a/src/tests/helpers/e2etest.ts b/src/tests/helpers/e2etest.ts
index db21f2d8c160..7bd87f4b8bd5 100644
--- a/src/tests/helpers/e2etest.ts
+++ b/src/tests/helpers/e2etest.ts
@@ -34,19 +34,10 @@ interface ResponseWithHeaders<T> {
   ok: boolean
 }
 
-// Type alias for cached DOM results to improve maintainability
 type CachedDOMResult = CheerioAPI & { res: ResponseWithHeaders<string>; $: CheerioAPI }
 
-// Cache to store DOM objects
 const getDOMCache = new Map<string, CachedDOMResult>()
 
-/**
- * Makes an HTTP request using the specified method and options.
- *
- * @param route - The route to request.
- * @param options - Configuration options for the request.
- * @returns A promise that resolves to the HTTP response.
- */
 export async function get<T extends ResponseTypes = 'text'>(
   route: string,
   options: GetOptions<T> = {},
@@ -61,7 +52,6 @@ export async function get<T extends ResponseTypes = 'text'>(
     retries = 0,
   } = options
 
-  // Construct the options for the fetch request
   const fetchOptions: RequestInit = omitBy(
     {
       method: method.toUpperCase(),
@@ -72,13 +62,11 @@ export async function get<T extends ResponseTypes = 'text'>(
     isUndefined,
   )
 
-  // Perform the HTTP request
   const response = await fetchWithRetry(`http://localhost:4000${route}`, fetchOptions, {
     retries,
     throwHttpErrors: false,
   })
 
-  // Get response body based on responseType
   let responseBody: ResponseTypeMap[T]
   if (responseType === 'json') {
     responseBody = (await response.json()) as ResponseTypeMap[T]
@@ -89,7 +77,6 @@ export async function get<T extends ResponseTypes = 'text'>(
     responseBody = (await response.text()) as ResponseTypeMap[T]
   }
 
-  // Convert headers to record format
   const headersRecord: Record<string, string> = {}
   for (const [key, value] of response.headers) {
     headersRecord[key] = value
@@ -105,13 +92,6 @@ export async function get<T extends ResponseTypes = 'text'>(
   } as ResponseWithHeaders<ResponseTypeMap[T]>
 }
 
-/**
- * Makes a HEAD HTTP request to the specified route.
- *
- * @param route - The route to request.
- * @param opts - Options for following redirects.
- * @returns A promise that resolves to the HTTP response.
- */
 export async function head(
   route: string,
   opts: { followRedirects?: boolean } = { followRedirects: false },
@@ -120,13 +100,6 @@ export async function head(
   return res
 }
 
-/**
- * Makes a POST HTTP request to the specified route.
- *
- * @param route - The route to request.
- * @param opts - Options for the request.
- * @returns A promise that resolves to the HTTP response.
- */
 export function post(
   route: string,
   opts: Omit<GetOptions, 'method'> = {},
@@ -134,14 +107,6 @@ export function post(
   return get(route, { ...opts, method: 'post' })
 }
 
-/**
- * Retrieves a cached DOM object for the specified route and options.
- * If the DOM is not cached, it fetches and caches it.
- *
- * @param route - The route to request.
- * @param options - Options for fetching the DOM.
- * @returns A promise that resolves to the cached DOM object.
- */
 export async function getDOMCached(
   route: string,
   options: GetDOMOptions = {},
@@ -155,13 +120,6 @@ export async function getDOMCached(
   return getDOMCache.get(key)!
 }
 
-/**
- * Fetches the DOM for the specified route and options.
- *
- * @param route - The route to request.
- * @param options - Options for fetching the DOM.
- * @returns A promise that resolves to the loaded DOM object with res attached and destructurable.
- */
 export async function getDOM(route: string, options: GetDOMOptions = {}): Promise<CachedDOMResult> {
   const { headers, allow500s = false, allow404 = false, retries = 0 } = options
   const res = await get(route, { followRedirects: true, headers, retries })
@@ -184,13 +142,6 @@ export async function getDOM(route: string, options: GetDOMOptions = {}): Promis
   return result
 }
 
-/**
- * Fetches and parses JSON from the specified route.
- *
- * @param route - The route to request.
- * @param opts - Options for the request.
- * @returns A promise that resolves to the parsed JSON object.
- */
 export async function getJSON<T = unknown>(
   route: string,
   opts: Omit<GetOptions, 'method'> = {},
diff --git a/src/tests/lib/validate-json-schema.ts b/src/tests/lib/validate-json-schema.ts
index d2696060bd6a..b20418628e60 100644
--- a/src/tests/lib/validate-json-schema.ts
+++ b/src/tests/lib/validate-json-schema.ts
@@ -7,7 +7,6 @@ const ajv = new Ajv({ allErrors: true, allowUnionTypes: true })
 addFormats(ajv)
 addErrors(ajv)
 
-// Custom JSON keywords
 ajv.addKeyword({
   keyword: 'translatable',
 })
@@ -22,7 +21,6 @@ ajv.addKeyword({
   type: 'string',
 })
 
-// Custom JSON formats
 ajv.addFormat('semver', {
   validate: (x: string): boolean => semver.validRange(x) !== null,
 })
diff --git a/src/tests/mocks/cse-copilot-mock.ts b/src/tests/mocks/cse-copilot-mock.ts
index 4163d2d22b3b..6e1d0e8b6094 100644
--- a/src/tests/mocks/cse-copilot-mock.ts
+++ b/src/tests/mocks/cse-copilot-mock.ts
@@ -4,11 +4,9 @@ import { Request, Response } from 'express'
 export const CSE_COPILOT_PREFIX = 'cse-copilot'
 
 export function cseCopilotPostAnswersMock(req: Request, res: Response) {
-  // Set headers for chunked transfer and encoding
   res.setHeader('Content-Type', 'application/json; charset=utf-8')
   res.setHeader('Transfer-Encoding', 'chunked')
 
-  // Define the SOURCES chunk
   const sourcesChunk = {
     chunkType: 'SOURCES',
     sources: [
@@ -30,21 +28,17 @@ export function cseCopilotPostAnswersMock(req: Request, res: Response) {
     ],
   }
 
-  // Function to send a chunk with proper encoding
   const sendEncodedChunk = (data: string, isLast = false) => {
-    const prefix = isLast ? '' : '\n' // Optionally, add delimiters if needed
+    const prefix = isLast ? '' : '\n'
     const buffer = Buffer.from(prefix + data, 'utf-8')
     res.write(buffer)
   }
 
-  // Send the SOURCES chunk
   sendEncodedChunk(`Chunk: ${JSON.stringify(sourcesChunk)}\n\n`)
 
-  // Define the message to be sent in chunks
   const message =
     'Creating a repository on GitHub is something you should already know how to do :shrug:'
 
-  // Split the message into words (or adjust the splitting logic as needed)
   const words = message.split(' ')
 
   let index = 0
@@ -55,17 +49,15 @@ export function cseCopilotPostAnswersMock(req: Request, res: Response) {
       const isLastWord = index === words.length - 1
       const chunk = {
         chunkType: 'MESSAGE_CHUNK',
-        text: word + (isLastWord ? '' : ' '), // Add space if not the last word
+        text: word + (isLastWord ? '' : ' '),
       }
       sendEncodedChunk(`${JSON.stringify(chunk)}\n`)
       index++
-      sendChunk() // Adjust the delay as needed
+      sendChunk()
     } else {
-      // End the response after all chunks are sent
       res.end()
     }
   }
 
-  // Start sending MESSAGE_CHUNKs
   sendChunk()
 }
diff --git a/src/tests/mocks/start-mock-server.ts b/src/tests/mocks/start-mock-server.ts
index 4ee1c493d062..9236b73a60e6 100644
--- a/src/tests/mocks/start-mock-server.ts
+++ b/src/tests/mocks/start-mock-server.ts
@@ -24,35 +24,27 @@ import express from 'express'
 import type { Server } from 'http'
 import { CSE_COPILOT_PREFIX, cseCopilotPostAnswersMock } from './cse-copilot-mock'
 
-// Define the default port for the mock server
 const MOCK_SERVER_PORT = 3012
 
-// Construct the server URL using the defined port
 const serverUrl = `http://localhost:${MOCK_SERVER_PORT}`
 
-// Variable to hold the server instance
 let server: Server | null = null
 
-// Override environment variables for testing purposes
 export function overrideEnvForTesting() {
   process.env.CSE_COPILOT_ENDPOINT = `${serverUrl}/${CSE_COPILOT_PREFIX}`
 }
 
-// Function to start the mock server
 export function startMockServer(port = MOCK_SERVER_PORT) {
   const app = express()
   app.use(express.json())
 
-  // Define your mock routes here
   app.post(`/${CSE_COPILOT_PREFIX}/answers`, cseCopilotPostAnswersMock)
 
-  // Start the server and store the server instance
   server = app.listen(port, () => {
     console.log(`Mock server is running on port ${port}`)
   })
 }
 
-// Function to stop the mock server
 export function stopMockServer(): Promise<void> {
   return new Promise((resolve, reject) => {
     if (server) {
diff --git a/src/tools/components/InArticlePicker.tsx b/src/tools/components/InArticlePicker.tsx
index e6682c912133..f8c9dbe52973 100644
--- a/src/tools/components/InArticlePicker.tsx
+++ b/src/tools/components/InArticlePicker.tsx
@@ -151,7 +151,7 @@ export const InArticlePicker = ({
   // After a user clicks a tab, the shallow route change updates `currentValue`.
   // Once the DOM reflects the new selection (aria-current="page" is on the new
   // tab), move keyboard focus there so the user's context is preserved.
-  // WCAG 2.4.3 Focus Order — focus must land on the triggered control.
+  // WCAG 2.4.3 Focus Order: focus must land on the triggered control.
   useEffect(() => {
     if (!focusAfterNavRef.current || !currentValue) return
     focusAfterNavRef.current = false
diff --git a/src/tools/components/PlatformPicker.tsx b/src/tools/components/PlatformPicker.tsx
index b0ab8782712b..7d78b2e48e6c 100644
--- a/src/tools/components/PlatformPicker.tsx
+++ b/src/tools/components/PlatformPicker.tsx
@@ -13,7 +13,7 @@ const platforms = [
   { value: 'linux', label: 'Linux' },
 ]
 
-// Nota bene: platform === os
+// Note: platform === os
 
 export const PlatformPicker = () => {
   const { defaultPlatform, detectedPlatforms } = useArticleContext()
diff --git a/src/tools/components/ToolPicker.tsx b/src/tools/components/ToolPicker.tsx
index 14a141a17924..94748f6b1523 100644
--- a/src/tools/components/ToolPicker.tsx
+++ b/src/tools/components/ToolPicker.tsx
@@ -3,13 +3,12 @@ import { InArticlePicker } from './InArticlePicker'
 import { useSelection } from './SelectionContext'
 import { TOOL_PREFERRED_COOKIE_NAME } from '@/frame/lib/constants'
 
-// example: http://localhost:4000/en/codespaces/developing-in-codespaces/creating-a-codespace
+// Example page with a tool picker:
+// http://localhost:4000/en/codespaces/developing-in-codespaces/creating-a-codespace
 
-// Nota bene: tool === application
-// Nota bene: picker === switcher
+// Note: tool === application, and picker === switcher
 
 function getDefaultTool(defaultTool: string | undefined, detectedTools: Array<string>): string {
-  // If there is a default tool and the tool is present on this page
   if (defaultTool && detectedTools.includes(defaultTool)) return defaultTool
 
   // Default to webui if present (this is generally the case where we show UI/CLI/Desktop info)
@@ -18,13 +17,11 @@ function getDefaultTool(defaultTool: string | undefined, detectedTools: Array<st
   // Default to cli if present (this is generally the case where we show curl/CLI info)
   if (detectedTools.includes('cli')) return 'cli'
 
-  // Otherwise, just choose the first detected tool
   return detectedTools[0]
 }
 
 const toolQueryKey = 'tool'
 export const ToolPicker = () => {
-  // allTools comes from the ArticleContext which contains the list of tools available
   const { defaultTool, detectedTools, allTools } = useArticleContext()
   const { setTool } = useSelection()
 
diff --git a/src/tools/lib/all-platforms.ts b/src/tools/lib/all-platforms.ts
index 5681f505b450..13845752f6a4 100644
--- a/src/tools/lib/all-platforms.ts
+++ b/src/tools/lib/all-platforms.ts
@@ -1,9 +1,4 @@
-/**
- * All platforms available for the Platform Picker
- */
+// All platforms available for the platform picker.
 export type Platform = 'mac' | 'windows' | 'linux'
 
-/**
- * Array of all supported platforms in the Platform Picker
- */
 export const allPlatforms: Platform[] = ['mac', 'windows', 'linux']
diff --git a/src/tools/lib/all-tools.ts b/src/tools/lib/all-tools.ts
index 55399ab720e2..db932c91334c 100644
--- a/src/tools/lib/all-tools.ts
+++ b/src/tools/lib/all-tools.ts
@@ -1,6 +1,4 @@
-/**
- * Interface defining the mapping between tool identifiers and their display names
- */
+// Maps each tool identifier to its display name.
 export interface ToolsMapping {
   [key: string]: string
 }
diff --git a/src/tools/scripts/liquid-markdown-tables/convert.ts b/src/tools/scripts/liquid-markdown-tables/convert.ts
index 587c5a40d5fe..eaf95e25050e 100644
--- a/src/tools/scripts/liquid-markdown-tables/convert.ts
+++ b/src/tools/scripts/liquid-markdown-tables/convert.ts
@@ -1,6 +1,4 @@
-/**
- * See docstring in index.ts for more information about how to use this script.
- */
+// See the comment at the top of index.ts for how to use this script.
 import fs from 'fs'
 
 import chalk from 'chalk'
diff --git a/src/tools/scripts/liquid-markdown-tables/index.ts b/src/tools/scripts/liquid-markdown-tables/index.ts
index e904256eb8b8..04b093a4125b 100644
--- a/src/tools/scripts/liquid-markdown-tables/index.ts
+++ b/src/tools/scripts/liquid-markdown-tables/index.ts
@@ -56,7 +56,6 @@ program
   .command('convert')
   .description('Clean up Markdown tables that use Liquid `ifversion` tags the old/wrong way')
   .option('--dry-run', "Don't actually write changes to disk", false)
-  //   .arguments('[files-or-directories...]', '')
   .arguments('[files...]')
   .action(convert)
 
diff --git a/src/tools/scripts/liquid-markdown-tables/lib.ts b/src/tools/scripts/liquid-markdown-tables/lib.ts
index 6c071d055a42..ec15b03812d0 100644
--- a/src/tools/scripts/liquid-markdown-tables/lib.ts
+++ b/src/tools/scripts/liquid-markdown-tables/lib.ts
@@ -6,7 +6,6 @@ const endifIfVersionRegex = /\|({%-?\s*endif\s*%})({%-?\sifversion\s+([\w- ]+)\s
 const endifRegex = /\|({%-?\s*endif\s*%})\n/
 const endifAloneRegex = /^({%-?\s*endif\s*%})\n/
 
-// Split a string by newlines while keeping the newlines
 function splitAndKeepNewlines(str: string) {
   const lines = str.split(/(\r\n|\r|\n)/)
   const result: string[] = []
diff --git a/src/versions/lib/all-versions.ts b/src/versions/lib/all-versions.ts
index 92e7e387a2e7..b502f0d7932a 100644
--- a/src/versions/lib/all-versions.ts
+++ b/src/versions/lib/all-versions.ts
@@ -9,7 +9,6 @@ const versionDelimiter = '@'
 const latestNonNumberedRelease = 'latest'
 const REST_DATA_META_FILE = 'src/rest/lib/config.json'
 
-// Type for the plan configuration
 interface PlanConfig {
   plan: string
   planTitle: string
@@ -22,7 +21,6 @@ interface PlanConfig {
   miscBaseName: string
 }
 
-// Type for the REST API config file
 interface RestApiConfig {
   'api-versions': {
     [key: string]: string[]
@@ -134,7 +132,7 @@ export function isApiVersioned(version: string): boolean {
 
 // Currently the versions from the OpenAPI do not match the versions on Docs.
 // There is a mapping between the version names. This gets the Docs version from
-// the OpenAPI version name (the filename )
+// the OpenAPI version name.
 export function getDocsVersion(openApiVersion: string): string {
   const matchingVersion = Object.values(allVersions).find((version) =>
     openApiVersion.startsWith(version.openApiVersionName),
diff --git a/src/versions/lib/enterprise-server-releases.d.ts b/src/versions/lib/enterprise-server-releases.d.ts
index e7405ea5b3a8..85f2391e2272 100644
--- a/src/versions/lib/enterprise-server-releases.d.ts
+++ b/src/versions/lib/enterprise-server-releases.d.ts
@@ -1,7 +1,3 @@
-// ============================================================================
-// TYPE DEFINITIONS
-// ============================================================================
-
 type Dates = {
   [key: string]: {
     releaseDate: string // For backward compatibility - will be RC date initially, then GA date once available
@@ -13,10 +9,6 @@ type Dates = {
   }
 }
 
-// ============================================================================
-// STATICALLY DEFINED VALUES
-// ============================================================================
-
 export const next: string
 export const nextNext: string
 export const supported: string[]
@@ -31,10 +23,6 @@ export const lastReleaseWithLegacyFormat: string
 export const firstReleaseNote: string
 export const firstRestoredAdminGuides: string
 
-// ============================================================================
-// COMPUTED VALUES
-// ============================================================================
-
 export const all: string[]
 export const latest: string
 export const latestStable: string
@@ -48,18 +36,10 @@ export const deprecatedReleasesWithLegacyFormat: string[]
 export const deprecatedReleasesWithNewFormat: string[]
 export const deprecatedReleasesOnDeveloperSite: string[]
 
-// ============================================================================
-// HELPER FUNCTIONS
-// ============================================================================
-
 export declare function findReleaseNumberIndex(releaseNum: string): number
 export declare function getNextReleaseNumber(releaseNum: string): string
 export declare function getPreviousReleaseNumber(releaseNum: string): string
 
-// ============================================================================
-// DEFAULT EXPORT
-// ============================================================================
-
 const allExports = {
   next,
   nextNext,
diff --git a/src/versions/lib/enterprise-server-releases.ts b/src/versions/lib/enterprise-server-releases.ts
index 566902bba9d0..49511d28cc48 100644
--- a/src/versions/lib/enterprise-server-releases.ts
+++ b/src/versions/lib/enterprise-server-releases.ts
@@ -24,10 +24,6 @@ const rawDates: RawDatesData = JSON.parse(
   fs.readFileSync('src/ghes-releases/lib/enterprise-dates.json', 'utf8'),
 )
 
-// ============================================================================
-// STATICALLY DEFINED VALUES
-// ============================================================================
-
 // Upcoming GHES release numbers (used in frontmatter and release planning)
 export const next = '3.23'
 export const nextNext = '3.24'
@@ -92,7 +88,6 @@ export const deprecated = [
 // Versions with legacy asset handling (stored in separate repos before blob storage)
 export const legacyAssetVersions = ['3.0', '2.22', '2.21']
 
-// Historical milestones that mark feature/process changes
 export const firstReleaseStoredInBlobStorage = '3.2'
 export const firstVersionDeprecatedOnNewSite = '2.13'
 export const lastVersionWithoutArchivedRedirectsFile = '2.17'
@@ -100,14 +95,8 @@ export const lastReleaseWithLegacyFormat = '2.18' // Last to use /enterprise/<re
 export const firstReleaseNote = '2.20'
 export const firstRestoredAdminGuides = '2.21'
 
-// ============================================================================
-// COMPUTED VALUES
-// ============================================================================
-
-// All versions (supported + deprecated)
 export const all = supported.concat(deprecated)
 
-// Latest and stable version helpers
 export const latest = supported[0]
 export const latestStable = releaseCandidate ? supported[1] : latest
 export const oldestSupported = supported[supported.length - 1]
@@ -124,7 +113,6 @@ export const dates: Record<string, EnhancedVersionDateData> = Object.fromEntries
   ]),
 ) as Record<string, EnhancedVersionDateData>
 
-// Deprecation tracking
 export const nextDeprecationDate = dates[oldestSupported].deprecationDate
 export const isOldestReleaseDeprecated = nextDeprecationDate
   ? new Date() > new Date(nextDeprecationDate)
@@ -136,7 +124,6 @@ export const releasesWithOldestDeprecationDate = Object.entries(dates)
   .filter(([, versionData]) => versionData.deprecationDate === nextDeprecationDate)
   .map(([version]) => version)
 
-// Filtered version arrays for different use cases
 export const deprecatedOnNewSite = deprecated.filter((version) =>
   versionSatisfiesRange(version, '>=2.13'),
 )
@@ -153,16 +140,8 @@ export const deprecatedReleasesOnDeveloperSite = deprecated.filter((version) =>
   versionSatisfiesRange(version, '<=2.16'),
 )
 
-// ============================================================================
-// HELPER FUNCTIONS
-// ============================================================================
-
-/**
- * Determines if a release date should be displayed based on current time.
- * Only shows dates that have already occurred to avoid showing future release dates.
- * @param {string|null} date - ISO date string
- * @returns {string|null} - Date string if in the past, null if future or invalid
- */
+// Returns the date only once it has passed, so we never advertise a future
+// release date. An unparseable date gives NaN, which also returns null.
 function processDateForDisplay(date: string | undefined): string | null {
   if (!date) return null
   const currentTimestamp = Math.floor(Date.now() / 1000)
@@ -170,12 +149,7 @@ function processDateForDisplay(date: string | undefined): string | null {
   return dateTimestamp <= currentTimestamp ? date : null
 }
 
-/**
- * Validates that version sequence is correct (each version is exactly one release ahead)
- * @param {string} v1 - Current version
- * @param {string} v2 - Next version
- * @throws {Error} If version sequence is invalid
- */
+// Throws unless v2 is exactly one release ahead of v1.
 function isValidNext(v1: string, v2: string): void {
   const semverV1 = semver.coerce(v1)!.raw
   const semverV2 = semver.coerce(v2)!.raw
@@ -197,14 +171,9 @@ export const getPreviousReleaseNumber = (releaseNum: string): string => {
   return all[findReleaseNumberIndex(releaseNum) + 1]
 }
 
-// Validate that version sequence is correct
 isValidNext(supported[0], next)
 isValidNext(next, nextNext)
 
-// ============================================================================
-// DEFAULT EXPORT
-// ============================================================================
-
 export default {
   next,
   nextNext,
diff --git a/src/versions/lib/get-applicable-versions.ts b/src/versions/lib/get-applicable-versions.ts
index e117ac3f23af..cba545b0cf0b 100644
--- a/src/versions/lib/get-applicable-versions.ts
+++ b/src/versions/lib/get-applicable-versions.ts
@@ -77,11 +77,9 @@ function getApplicableVersions(
           {},
         )
 
-  // Get available versions for feature and standard versions.
   const foundFeatureVersions = evaluateVersions(featureVersionsObj)
   const foundStandardVersions = typeof versionsObj === 'string' ? [] : evaluateVersions(versionsObj)
 
-  // Combine them!
   const applicableVersions: string[] = Array.from(
     new Set(foundStandardVersions.concat(foundFeatureVersions)),
   )
@@ -97,7 +95,6 @@ function getApplicableVersions(
     return allVersionKeys.indexOf(v)
   })
 
-  // Strip out not-yet-supported versions if the option to include them is not provided.
   if (!opts.includeNextVersion) {
     sortedVersions = sortedVersions.filter(
       (v: string) => !(v.endsWith(`@${next}`) || v.endsWith(`@${nextNext}`)),
@@ -117,7 +114,6 @@ function evaluateVersions(versionsObj: VersionsObject): string[] {
   //   ghec: '*'
   // ^ where each key corresponds to a plan's short name (defined in lib/all-versions.ts)
   for (const [plan, planValue] of Object.entries(versionsObj)) {
-    // Skip non-string plan values for semantic comparison
     if (typeof planValue !== 'string') continue
 
     // For each available plan (e.g., `ghes`), get the matching versions from allVersions.

From 5695f5e3214fd8ab62d2aa889a6fb77ae5bb9fc3 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:19:48 +0000
Subject: [PATCH 11/16] Trim comments in ai-tools, shielding, and
 automated-pipelines (#63245)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/ai-tools/lib/auth-utils.ts                |  3 +-
 src/ai-tools/lib/call-models-api.ts           |  6 ---
 src/ai-tools/lib/file-utils.ts                | 17 ++------
 src/ai-tools/lib/prompt-utils.ts              | 26 ++----------
 src/ai-tools/lib/spaces-utils.ts              | 15 -------
 src/ai-tools/scripts/ai-tools.ts              | 30 +++-----------
 .../lib/update-markdown.ts                    | 40 +++++--------------
 src/automated-pipelines/tests/rendering.ts    |  2 -
 .../tests/update-markdown.ts                  |  3 --
 .../middleware/handle-invalid-paths.ts        |  4 +-
 .../handle-invalid-query-strings.ts           |  2 -
 .../middleware/handle-malformed-urls.ts       | 10 ++---
 .../middleware/handle-old-next-data-paths.ts  |  1 -
 src/shielding/tests/invalid-querystrings.ts   |  2 +-
 src/shielding/tests/malformed-urls.ts         |  6 +--
 15 files changed, 33 insertions(+), 134 deletions(-)

diff --git a/src/ai-tools/lib/auth-utils.ts b/src/ai-tools/lib/auth-utils.ts
index 9639c6fc35b0..c85ebaba54e5 100644
--- a/src/ai-tools/lib/auth-utils.ts
+++ b/src/ai-tools/lib/auth-utils.ts
@@ -1,7 +1,8 @@
 import { execSync } from 'child_process'
 
 /**
- * Ensure GitHub token is available, exiting process if not found
+ * Falls back to the gh CLI token, setting process.env.GITHUB_TOKEN.
+ * Exits the process if neither is available.
  */
 export function ensureGitHubToken(): void {
   if (!process.env.GITHUB_TOKEN) {
diff --git a/src/ai-tools/lib/call-models-api.ts b/src/ai-tools/lib/call-models-api.ts
index 70e2a90b6f58..db8883f7c536 100644
--- a/src/ai-tools/lib/call-models-api.ts
+++ b/src/ai-tools/lib/call-models-api.ts
@@ -42,7 +42,6 @@ export async function callModelsApi(
 ): Promise<string> {
   let aiResponse: ChatCompletionChoice
 
-  // Set default model if none specified
   if (!promptWithContent.model) {
     promptWithContent.model = DEFAULT_MODEL
     if (verbose) {
@@ -51,7 +50,6 @@ export async function callModelsApi(
   }
 
   try {
-    // Create an AbortController for timeout handling
     const controller = new AbortController()
     const timeoutId = setTimeout(() => controller.abort(), API_TIMEOUT_MS)
 
@@ -82,7 +80,6 @@ export async function callModelsApi(
     if (!response.ok) {
       let errorMessage = `HTTP error! status: ${response.status} - ${response.statusText}`
 
-      // Try to get more detailed error information
       try {
         const errorBody = await response.json()
         if (errorBody.error && errorBody.error.message) {
@@ -92,7 +89,6 @@ export async function callModelsApi(
         // If we can't parse error body, continue with basic error
       }
 
-      // Add helpful hints for common errors
       if (response.status === 401) {
         errorMessage += ' (Check your GITHUB_TOKEN)'
       } else if (response.status === 400) {
@@ -135,9 +131,7 @@ export async function callModelsApi(
   return cleanAIResponse(aiResponse.message.content)
 }
 
-// Helper function to clean up AI response content
 function cleanAIResponse(content: string): string {
-  // Remove markdown code blocks
   return content
     .replace(/^```[\w]*\n/gm, '') // Remove opening code blocks
     .replace(/\n```$/gm, '') // Remove closing code blocks at end
diff --git a/src/ai-tools/lib/file-utils.ts b/src/ai-tools/lib/file-utils.ts
index d113396793bd..63cbe92a10e7 100644
--- a/src/ai-tools/lib/file-utils.ts
+++ b/src/ai-tools/lib/file-utils.ts
@@ -6,9 +6,6 @@ import { schema } from '@/frame/lib/frontmatter'
 
 const MAX_DIRECTORY_DEPTH = 20
 
-/**
- * Enhanced recursive markdown file finder with symlink, depth, and root path checks
- */
 export function findMarkdownFiles(
   dir: string,
   rootDir: string,
@@ -33,7 +30,6 @@ export function findMarkdownFiles(
     return []
   }
   visited.add(realDir)
-  // Prevent excessive depth
   if (depth > maxDepth) {
     return []
   }
@@ -71,9 +67,8 @@ interface FrontmatterProperties {
 }
 
 /**
- * Function to merge new frontmatter properties into existing file while preserving formatting.
- * Uses surgical replacement to only modify the specific field(s) being updated,
- * preserving all original YAML formatting for unchanged fields.
+ * Replaces only the fields being updated, so the original YAML formatting
+ * of every other field survives.
  */
 export function mergeFrontmatterProperties(filePath: string, newPropertiesYaml: string): string {
   const content = fs.readFileSync(filePath, 'utf8')
@@ -90,7 +85,7 @@ export function mergeFrontmatterProperties(filePath: string, newPropertiesYaml:
   }
 
   try {
-    // Clean up the AI response - remove markdown code blocks if present
+    // The model often wraps its output in a code fence.
     let cleanedYaml = newPropertiesYaml.trim()
     cleanedYaml = cleanedYaml.replace(/^```ya?ml\s*\n/i, '')
     cleanedYaml = cleanedYaml.replace(/\n```\s*$/i, '')
@@ -111,12 +106,10 @@ export function mergeFrontmatterProperties(filePath: string, newPropertiesYaml:
       }),
     )
 
-    // Split content into lines for surgical replacement
     const lines = content.split('\n')
     let inFrontmatter = false
     let frontmatterEndIndex = -1
 
-    // Find frontmatter boundaries
     for (let i = 0; i < lines.length; i++) {
       if (lines[i].trim() === '---') {
         if (!inFrontmatter) {
@@ -128,17 +121,14 @@ export function mergeFrontmatterProperties(filePath: string, newPropertiesYaml:
       }
     }
 
-    // Replace each field value while preserving everything else
     for (const [key, value] of Object.entries(sanitizedProperties)) {
       const formattedValue = typeof value === 'string' ? `'${value.replace(/'/g, "''")}'` : value
 
-      // Find the line with this field
       let foundField = false
       for (let i = 1; i < frontmatterEndIndex; i++) {
         const line = lines[i]
         if (line.startsWith(`${key}:`)) {
           foundField = true
-          // Simple replacement: keep the field name and spacing, replace the value
           const colonIndex = line.indexOf(':')
           const leadingSpace = line.substring(colonIndex + 1, colonIndex + 2) // Usually a space
           lines[i] = `${key}:${leadingSpace}${formattedValue}`
@@ -153,7 +143,6 @@ export function mergeFrontmatterProperties(filePath: string, newPropertiesYaml:
         }
       }
 
-      // If field doesn't exist, add it before the closing ---
       if (!foundField && frontmatterEndIndex > 0) {
         lines.splice(frontmatterEndIndex, 0, `${key}: ${formattedValue}`)
         frontmatterEndIndex++
diff --git a/src/ai-tools/lib/prompt-utils.ts b/src/ai-tools/lib/prompt-utils.ts
index 1715d7bc2202..7d5f875ba348 100644
--- a/src/ai-tools/lib/prompt-utils.ts
+++ b/src/ai-tools/lib/prompt-utils.ts
@@ -17,17 +17,11 @@ export interface PromptData {
   max_tokens?: number
 }
 
-/**
- * Get the prompts directory path
- */
 export function getPromptsDir(): string {
   const __dirname = path.dirname(fileURLToPath(import.meta.url))
   return path.join(__dirname, '../prompts')
 }
 
-/**
- * Dynamically discover available editor types from prompt files
- */
 export function getAvailableEditorTypes(promptDir: string): string[] {
   const editorTypes: string[] = []
 
@@ -46,16 +40,10 @@ export function getAvailableEditorTypes(promptDir: string): string[] {
   return editorTypes
 }
 
-/**
- * Get formatted description of available refinement types
- */
 export function getRefinementDescriptions(editorTypes: string[]): string {
   return editorTypes.join(', ')
 }
 
-/**
- * Enrich context for intro prompt on index.md files
- */
 export function enrichIndexContext(filePath: string, content: string): string {
   if (!filePath.endsWith('index.md')) return content
 
@@ -72,7 +60,6 @@ export function enrichIndexContext(filePath: string, content: string): string {
           .join(' ')
       : ''
 
-    // Get child article titles
     const titles: string[] = []
     if (data.children && Array.isArray(data.children)) {
       const dir = path.dirname(filePath)
@@ -94,7 +81,6 @@ export function enrichIndexContext(filePath: string, content: string): string {
       }
     }
 
-    // Build context note
     const parts: string[] = []
     if (productName) parts.push(`Product: ${productName}`)
     if (titles.length > 0) parts.push(`Child articles: ${titles.join(', ')}`)
@@ -114,24 +100,19 @@ export function enrichIndexContext(filePath: string, content: string): string {
   return content
 }
 
-/**
- * Call an editor with the given content and options
- */
 export async function callEditor(
   editorType: string,
   content: string,
   promptDir: string,
   writeMode: boolean,
   verbose = false,
-  promptContent?: string, // Optional: use this instead of reading from file
+  promptContent?: string, // Use this instead of reading a prompt file
 ): Promise<string> {
   let markdownPrompt: string
 
   if (promptContent) {
-    // Use provided prompt content (e.g., from Copilot Space)
     markdownPrompt = promptContent
   } else {
-    // Read from file
     const markdownPromptPath = path.join(promptDir, `${editorType}.md`)
 
     if (!fs.existsSync(markdownPromptPath)) {
@@ -144,7 +125,6 @@ export async function callEditor(
 
   const prompt = load(fs.readFileSync(promptTemplatePath, 'utf8')) as PromptData
 
-  // Validate the prompt template has required properties
   if (!prompt.messages || !Array.isArray(prompt.messages)) {
     throw new Error('Invalid prompt template: missing or invalid messages array')
   }
@@ -152,7 +132,8 @@ export async function callEditor(
   for (const msg of prompt.messages) {
     msg.content = msg.content.replace('{{markdownPrompt}}', markdownPrompt)
     msg.content = msg.content.replace('{{input}}', content)
-    // Replace writeMode template variable with simple string replacement
+    // Resolve the write-mode markers, then strip whatever they marked
+    // for removal.
     msg.content = msg.content.replace(
       /<!-- IF_WRITE_MODE -->/g,
       writeMode ? '' : '<!-- REMOVE_START -->',
@@ -166,7 +147,6 @@ export async function callEditor(
       writeMode ? '' : '<!-- REMOVE_END -->',
     )
 
-    // Remove sections marked for removal
     msg.content = msg.content.replace(/<!-- REMOVE_START -->[\s\S]*?<!-- REMOVE_END -->/g, '')
   }
 
diff --git a/src/ai-tools/lib/spaces-utils.ts b/src/ai-tools/lib/spaces-utils.ts
index e5859ec5b338..e0f993b3b046 100644
--- a/src/ai-tools/lib/spaces-utils.ts
+++ b/src/ai-tools/lib/spaces-utils.ts
@@ -1,6 +1,3 @@
-/**
- * Copilot Space API response types
- */
 import { fetchWithRetry, readBodyWithTimeout } from '@/frame/lib/fetch-utils'
 
 export interface SpaceResource {
@@ -25,9 +22,6 @@ export interface SpaceData {
   updated_at: string
 }
 
-/**
- * Parse a Copilot Space URL to extract org and space ID
- */
 export function parseSpaceUrl(url: string): { org: string; id: string } {
   // Expected format: https://api.github.com/orgs/{org}/copilot-spaces/{id}
   const match = url.match(/\/orgs\/([^/]+)\/copilot-spaces\/(\d+)/)
@@ -44,9 +38,6 @@ export function parseSpaceUrl(url: string): { org: string; id: string } {
   }
 }
 
-/**
- * Fetch a Copilot Space from the GitHub API
- */
 export async function fetchCopilotSpace(spaceUrl: string): Promise<SpaceData> {
   const { org, id } = parseSpaceUrl(spaceUrl)
   const apiUrl = `https://api.github.com/orgs/${org}/copilot-spaces/${id}`
@@ -88,26 +79,20 @@ export async function fetchCopilotSpace(spaceUrl: string): Promise<SpaceData> {
   return (await readBodyWithTimeout(response, () => response.json(), 30_000)) as SpaceData
 }
 
-/**
- * Convert a Copilot Space to a markdown prompt file
- */
 export function convertSpaceToPrompt(space: SpaceData): string {
   const timestamp = new Date().toISOString()
   const lines: string[] = []
 
-  // Header with metadata
   lines.push(`<!-- Generated from Copilot Space: ${space.name} -->`)
   lines.push(`<!-- Space ID: ${space.number} | Generated: ${timestamp} -->`)
   lines.push(`<!-- Space URL: ${space.html_url} -->`)
   lines.push('')
 
-  // General instructions
   if (space.general_instructions) {
     lines.push(space.general_instructions.trim())
     lines.push('')
   }
 
-  // Add each resource as a context section
   if (space.resources_attributes && space.resources_attributes.length > 0) {
     for (const resource of space.resources_attributes) {
       if (resource.resource_type === 'free_text' && resource.metadata) {
diff --git a/src/ai-tools/scripts/ai-tools.ts b/src/ai-tools/scripts/ai-tools.ts
index 62f2d3a04cfb..2c66e8c72938 100644
--- a/src/ai-tools/scripts/ai-tools.ts
+++ b/src/ai-tools/scripts/ai-tools.ts
@@ -19,7 +19,6 @@ dotenv.config({ quiet: true })
 
 const promptDir = getPromptsDir()
 
-// Ensure GitHub token is available
 ensureGitHubToken()
 
 const editorTypes = getAvailableEditorTypes(promptDir)
@@ -68,7 +67,7 @@ program
   .option('-f, --files <files...>', 'One or more content file paths in the content directory')
   .action((options: CliOptions) => {
     ;(async () => {
-      // Handle export-space workflow (standalone, doesn't process files)
+      // The export-space workflow is standalone and processes no files.
       if (options.exportSpace) {
         if (!options.output) {
           console.error('Error: --export-space requires --output option')
@@ -95,13 +94,11 @@ program
         }
       }
 
-      // Validate mutually exclusive options
       if (options.space && options.prompt) {
         console.error('Error: Cannot use both --space and --prompt options')
         process.exit(1)
       }
 
-      // Files are required for processing workflows
       if (!options.files || options.files.length === 0) {
         console.error('Error: --files option is required (unless using --export-space)')
         process.exit(1)
@@ -113,7 +110,7 @@ program
       let prompts: string[] = []
       let promptContent: string | undefined
 
-      // Handle Space workflow (in-memory)
+      // Build the prompt in memory instead of reading a prompt file.
       if (options.space) {
         try {
           spinner.text = 'Fetching Copilot Space...'
@@ -130,7 +127,6 @@ program
           process.exit(1)
         }
       } else {
-        // Handle local prompt workflow
         prompts = options.prompt || options.refine || []
 
         if (prompts.length === 0) {
@@ -140,7 +136,7 @@ program
         }
       }
 
-      // Validate local prompt types exist (skip for Space workflow)
+      // A Space prompt is not a local file, so there is nothing to validate.
       if (!options.space) {
         const availableEditors = editorTypes
         for (const editor of prompts) {
@@ -168,16 +164,13 @@ program
           continue
         }
 
-        // Check if it's a directory
         const isDirectory = fs.statSync(filePath).isDirectory()
 
         for (const editorType of prompts) {
           try {
-            // For other editor types, process individual files
             const filesToProcess: string[] = []
 
             if (isDirectory) {
-              // Find all markdown files in the directory recursively
               // Use process.cwd() as the root directory for safety
               const rootDir = fs.realpathSync(process.cwd())
               filesToProcess.push(...findMarkdownFiles(filePath, rootDir))
@@ -197,7 +190,7 @@ program
               const relativePath = path.relative(process.cwd(), fileToProcess)
               spinner.text = `Processing: ${relativePath}`
               try {
-                // Expand Liquid references before processing
+                // Capture the intro before Liquid expansion rewrites it.
                 let originalIntro = ''
                 if (editorType === 'intro') {
                   const originalContent = fs.readFileSync(fileToProcess, 'utf8')
@@ -212,7 +205,6 @@ program
 
                 let content = fs.readFileSync(fileToProcess, 'utf8')
 
-                // For intro prompt, add original intro and enrich context
                 if (editorType === 'intro') {
                   if (originalIntro) {
                     content = `\n\n---\nOriginal intro (unresolved): ${originalIntro}\n---\n\n${content}`
@@ -220,7 +212,6 @@ program
                   content = enrichIndexContext(fileToProcess, content)
                 }
 
-                // For content-type prompt, skip files that already have contentType
                 if (editorType === 'content-type' && content.includes('contentType:')) {
                   spinner.stop()
                   console.log(`⏭️  Skipping ${relativePath} (already has contentType)`)
@@ -240,24 +231,22 @@ program
 
                 if (options.write) {
                   if (editorType === 'intro' || editorType === 'content-type') {
-                    // For frontmatter addition/modification, merge properties instead of overwriting entire file
+                    // Merge frontmatter instead of overwriting the whole file.
                     const updatedContent = mergeFrontmatterProperties(fileToProcess, answer)
                     fs.writeFileSync(fileToProcess, updatedContent, 'utf8')
                     console.log(`✅ Added frontmatter properties to: ${relativePath}`)
                   } else {
-                    // For other editor types, write the full result back to the original file
                     fs.writeFileSync(fileToProcess, answer, 'utf8')
                     console.log(`✅ Updated: ${relativePath}`)
                   }
                 } else {
-                  // Just output to console (current behavior)
                   if (filesToProcess.length > 1) {
                     console.log(`\n=== ${relativePath} ===`)
                   }
                   console.log(answer)
                 }
 
-                // Always restore Liquid references after processing (even in non-write mode)
+                // Restore Liquid references even when not writing.
                 if (options.verbose) {
                   console.log(`Restoring Liquid references in: ${relativePath}`)
                 }
@@ -271,7 +260,6 @@ program
                 try {
                   runLiquidTagsScript('restore', [fileToProcess], false)
                 } catch (restoreError) {
-                  // Log restore failures in verbose mode for debugging
                   if (options.verbose) {
                     console.error(`Warning: Failed to restore Liquid references: ${restoreError}`)
                   }
@@ -291,7 +279,6 @@ program
 
       spinner.stop()
 
-      // Exit with appropriate code based on whether any errors occurred
       if (process.exitCode) {
         process.exit(process.exitCode)
       }
@@ -300,9 +287,6 @@ program
 
 program.parse(process.argv)
 
-/**
- * Run liquid-tags command on specified file paths
- */
 function runLiquidTagsScript(
   command: 'expand' | 'restore',
   filePaths: string[],
@@ -314,7 +298,6 @@ function runLiquidTagsScript(
   }
 
   try {
-    // Run liquid-tags script via tsx
     const liquidTagsScriptPath = path.join(
       process.cwd(),
       'src/content-render/scripts/liquid-tags.ts',
@@ -330,7 +313,6 @@ function runLiquidTagsScript(
   }
 }
 
-// Handle graceful shutdown
 process.on('SIGINT', () => {
   console.log('\n\n🛑 Process interrupted by user')
   process.exit(0)
diff --git a/src/automated-pipelines/lib/update-markdown.ts b/src/automated-pipelines/lib/update-markdown.ts
index 49addfc6ee14..964e0c78bce2 100644
--- a/src/automated-pipelines/lib/update-markdown.ts
+++ b/src/automated-pipelines/lib/update-markdown.ts
@@ -14,7 +14,6 @@ import type { MarkdownFrontmatter } from '@/types'
 
 const logger = createLogger(import.meta.url)
 
-// Type definitions - extending existing type to add missing fields and make most fields optional
 type FrontmatterData = Partial<MarkdownFrontmatter> & {
   autogenerated?: string
   [key: string]: unknown
@@ -67,8 +66,9 @@ type ChildrenComparison = {
 const ROOT_INDEX_FILE = 'content/index.md'
 export const MARKDOWN_COMMENT = '\n<!-- Content after this section is automatically generated -->\n'
 
-// Main entrypoint into this module. This function adds, removes, and updates
-// versions frontmatter in all directories under the targetDirectory.
+// Main entrypoint into this module.
+// Walks every directory under targetDirectory, adding and removing Markdown
+// files and keeping the index.md children and versions frontmatter in sync.
 export async function updateContentDirectory({
   targetDirectory,
   sourceContent,
@@ -87,7 +87,6 @@ async function removeMarkdownFiles(
   sourceFiles: string[],
   autogeneratedType: string | undefined,
 ): Promise<void> {
-  // Copy the autogenerated Markdown files to the target directory
   const autogeneratedFiles = await getAutogeneratedFiles(targetDirectory, autogeneratedType)
   // If the first array contains items that the second array does not,
   // it means that a Markdown page was deleted from the OpenAPI schema
@@ -98,7 +97,6 @@ async function removeMarkdownFiles(
       count: filesToRemove.length,
     })
   }
-  // Markdown files that need to be deleted
   for (const file of filesToRemove) {
     unlinkSync(file)
   }
@@ -140,19 +138,15 @@ async function updateMarkdownFiles(
   for (const [file, newContent] of Object.entries(sourceContent)) {
     await updateMarkdownFile(file, newContent.data, newContent.content)
   }
-  // This function recursively updates the index.md files in each
-  // of the directories under targetDirectory
   await updateDirectory(targetDirectory, frontmatter, { indexOrder })
-  // We don't want to update directories that the pipelines don't affect
-  // so we make one call to update only the root index.md file
-  // in targetDirectory to prevent any unintended changes
+  // The pipelines should not touch directories they do not own, so this
+  // call updates only the index.md file in the parent directory.
   await updateDirectory(path.dirname(targetDirectory), frontmatter, { rootDirectoryOnly: true })
 }
 
-// If the Markdown file already exists on disk, we only update the
-// content and version frontmatter to allow writers to manually
-// edit the modifiable content of the file. If the Markdown file doesn't
-// exists, we create a new Markdown file.
+// If the Markdown file already exists on disk, we update only the content
+// and the versions frontmatter, so writers can hand-edit the other fields.
+// If it does not exist, we create it.
 async function updateMarkdownFile(
   file: string,
   sourceData: FrontmatterData,
@@ -160,8 +154,6 @@ async function updateMarkdownFile(
   commentDelimiter: string = MARKDOWN_COMMENT,
 ): Promise<void> {
   if (existsSync(file)) {
-    // update only the versions property of the file, assuming
-    // the other properties have already been added and edited
     const { data, content } = matter(await readFile(file, 'utf-8'))
 
     // Double check that the comment delimiter is only used once
@@ -179,7 +171,6 @@ async function updateMarkdownFile(
     const isDelimiterMissing = !matches
     const isContentSame = automatedContent === sourceContent
     const isVersionsSame = isEqual(sourceData.versions, data.versions)
-    // Only proceed if the content or versions have changed
     if (isContentSame && isVersionsSame && !isDelimiterMissing) {
       logger.debug('Markdown file unchanged, skipping', { file })
       return
@@ -219,14 +210,12 @@ async function updateDirectory(
   { rootDirectoryOnly = false, shortTitle = false, indexOrder = {} }: UpdateDirectoryOptions = {},
 ): Promise<void> {
   const initialDirectoryListing = await getDirectoryInfo(directory)
-  // If there are no children on disk, remove the directory
   if (initialDirectoryListing.directoryContents.length === 0 && !rootDirectoryOnly) {
     logger.info('Removing empty directory', { directory })
     await rimraf(directory)
     return
   }
 
-  // Recursively update child directories
   if (!rootDirectoryOnly) {
     await Promise.all(
       initialDirectoryListing.childDirectories.map(async (subDirectory) => {
@@ -256,7 +245,6 @@ async function updateDirectory(
   }
 
   if (!rootDirectoryOnly) {
-    // Update the versions in the index.md file to match the directory contents
     directoryFiles.push(...childDirectories.map((dir) => path.join(dir, 'index.md')))
     const newVersions = await getIndexFileVersions(directory, directoryFiles)
     const isVersionEqual = isEqual(newVersions, data.versions)
@@ -265,7 +253,6 @@ async function updateDirectory(
     }
   }
 
-  // Update the index.md file contents and write the file to disk
   const dataUpdatedChildren = updateIndexChildren(
     data,
     { itemsToAdd, itemsToRemove },
@@ -295,7 +282,6 @@ function getChildrenToCompare(
 
   const isEarlyAccess = (item: string) => isRootIndexFile(indexFile) && item === 'early-access'
 
-  // Get the list of children from the directory contents
   const childrenOnDisk = directoryContents
     .map((file) => `${path.basename(file, '.md')}`)
     .filter((item) => !isEarlyAccess(item))
@@ -317,7 +303,7 @@ function getChildrenToCompare(
 // the order of the first items in the index files children
 // property. All other items are sorted and appended to list.
 //
-// 2. If not config is defined and the index file is an
+// 2. If no config is defined and the index file is an
 // autogenerated file, we sort all the children alphabetically.
 //
 // 3. If the index file is not autogenerated, we leave the ordering
@@ -332,7 +318,6 @@ function updateIndexChildren(
   const { itemsToAdd, itemsToRemove } = childUpdates
   const childPrefix = rootIndex ? '' : '/'
 
-  // Get a new list of children with added and removed items
   const children = [...(data.children || [])]
     // remove the '/' prefix used in index.md children
     .map((item) => item.replace(childPrefix, ''))
@@ -373,8 +358,8 @@ function updateIndexChildren(
   return updatedData
 }
 
-// Gets the contents of the index.md file from disk if it exits or
-// creates a new index.md file with the default frontmatter.
+// Gets the contents of the index.md file from disk if it exists,
+// or returns default frontmatter for a new one.
 async function getIndexFileContents(
   indexFile: string,
   frontmatter: FrontmatterData,
@@ -413,7 +398,6 @@ async function getIndexFileVersions(
           `File ${filepath} does not exist while assembling directory index.md files to create parent version.`,
         )
       }
-      // If not a markdown(x) file, skip it
       if (!file.endsWith('.md') && !file.endsWith('.mdx')) {
         return
       }
@@ -536,12 +520,10 @@ function checkVersionContinuity(versions: (string | undefined)[]): boolean {
   return availableVersions.every(Boolean)
 }
 
-// Returns true if the indexFile is the root index.md file
 function isRootIndexFile(indexFile: string): boolean {
   return indexFile === ROOT_INDEX_FILE
 }
 
-// Creates a new directory if it doesn't exist
 async function createDirectory(targetDirectory: string): Promise<void> {
   if (!existsSync(targetDirectory)) {
     await mkdirp(targetDirectory)
diff --git a/src/automated-pipelines/tests/rendering.ts b/src/automated-pipelines/tests/rendering.ts
index e4a1d2cb6e10..f8dfc17ca55f 100644
--- a/src/automated-pipelines/tests/rendering.ts
+++ b/src/automated-pipelines/tests/rendering.ts
@@ -6,7 +6,6 @@ import { describe, expect, test, vi } from 'vitest'
 import { loadPages } from '@/frame/lib/page-data'
 import { get } from '@/tests/helpers/e2etest'
 
-// Type definitions for page objects
 type Page = {
   autogenerated?: string
   fullPath: string
@@ -17,7 +16,6 @@ type Page = {
   }
 }
 
-// Get a list of the autogenerated pages
 const pageList: Page[] = await loadPages(undefined, ['en'])
 
 describe('autogenerated docs render', () => {
diff --git a/src/automated-pipelines/tests/update-markdown.ts b/src/automated-pipelines/tests/update-markdown.ts
index 210ffb9dc447..3b2290b86864 100644
--- a/src/automated-pipelines/tests/update-markdown.ts
+++ b/src/automated-pipelines/tests/update-markdown.ts
@@ -10,7 +10,6 @@ import type { FrontmatterVersions } from '@/types'
 
 import { updateContentDirectory } from '../lib/update-markdown'
 
-// Type definitions
 type ContentItem = {
   data: {
     title: string
@@ -92,8 +91,6 @@ describe('automated content directory updates', () => {
       contentDataFullPath[path.join(targetDirectory, key)] = newContentData[key]
     }
 
-    // Rewrites the content directory in the operating system's
-    // temp directory.
     await updateContentDirectory({
       targetDirectory,
       sourceContent: contentDataFullPath,
diff --git a/src/shielding/middleware/handle-invalid-paths.ts b/src/shielding/middleware/handle-invalid-paths.ts
index e8b8a9adc412..7b259d55c941 100644
--- a/src/shielding/middleware/handle-invalid-paths.ts
+++ b/src/shielding/middleware/handle-invalid-paths.ts
@@ -76,8 +76,8 @@ export default function handleInvalidPaths(
   next: NextFunction,
 ) {
   if (isJunkPath(req.path)) {
-    // We can all the CDN to cache these responses because they're
-    // they're not going to suddenly work in the next deployment.
+    // We can let the CDN cache these responses because they are not going
+    // to suddenly work in the next deployment.
     defaultCacheControl(res)
     res.status(404).type('text').send('Not found')
     return
diff --git a/src/shielding/middleware/handle-invalid-query-strings.ts b/src/shielding/middleware/handle-invalid-query-strings.ts
index 4020ff794953..df7c81577c12 100644
--- a/src/shielding/middleware/handle-invalid-query-strings.ts
+++ b/src/shielding/middleware/handle-invalid-query-strings.ts
@@ -65,9 +65,7 @@ export default function handleInvalidQuerystrings(
   if (method === 'GET' || method === 'HEAD') {
     const originalKeys = Object.keys(query)
 
-    // Check for invalid query string patterns (square brackets, etc.)
     const invalidKeys = originalKeys.filter((key) => {
-      // Check for square brackets which are invalid
       return key.includes('[') || key.includes(']')
     })
 
diff --git a/src/shielding/middleware/handle-malformed-urls.ts b/src/shielding/middleware/handle-malformed-urls.ts
index f4f13e75c4b3..a5e364b9543b 100644
--- a/src/shielding/middleware/handle-malformed-urls.ts
+++ b/src/shielding/middleware/handle-malformed-urls.ts
@@ -4,23 +4,19 @@ import { defaultCacheControl } from '@/frame/middleware/cache-control'
 import { ExtendedRequest } from '@/types'
 
 /**
- * Middleware to handle malformed UTF-8 sequences in URLs that cause
- * decodeURIComponent to fail. This prevents crashes from malicious
- * requests containing invalid URL-encoded sequences like %FF.
+ * Malformed UTF-8 in a URL, like `%FF`, makes decodeURIComponent throw.
+ * Express does not catch that while parsing, so without this the crash
+ * happens later at the router level.
  */
 export default function handleMalformedUrls(
   req: ExtendedRequest,
   res: Response,
   next: NextFunction,
 ) {
-  // Check URL for malformed UTF-8 sequences
-  // Express/router doesn't catch these during initial parsing - they cause
-  // crashes later when decodeURIComponent is called at the router level
   const url = req.originalUrl || req.url
   try {
     decodeURIComponent(url)
   } catch {
-    // If any decoding fails, this is a malformed URL
     defaultCacheControl(res)
     res.status(400).type('text').send('Bad Request: Malformed URL')
     return
diff --git a/src/shielding/middleware/handle-old-next-data-paths.ts b/src/shielding/middleware/handle-old-next-data-paths.ts
index 33417340f742..ac47f1883cbe 100644
--- a/src/shielding/middleware/handle-old-next-data-paths.ts
+++ b/src/shielding/middleware/handle-old-next-data-paths.ts
@@ -45,7 +45,6 @@ export default function handleOldNextDataPaths(
 
 let _buildId: string
 function getCurrentBuildID() {
-  // Simple memoization
   if (!_buildId) {
     _buildId = fs.readFileSync('.next/BUILD_ID', 'utf-8').trim()
   }
diff --git a/src/shielding/tests/invalid-querystrings.ts b/src/shielding/tests/invalid-querystrings.ts
index 1619ae7f25a1..23871850c62e 100644
--- a/src/shielding/tests/invalid-querystrings.ts
+++ b/src/shielding/tests/invalid-querystrings.ts
@@ -28,7 +28,7 @@ describe('invalid query strings', () => {
 
   test('302 redirect for many unrecognized query strings', async () => {
     // This test depends on knowing exactly the number
-    // of unrecognized query strings that will trigger a 400.
+    // of unrecognized query strings that will trigger a redirect.
     const sp = new URLSearchParams()
     for (const letter of alphabet.slice(0, MAX_UNFAMILIAR_KEYS_REDIRECT)) {
       sp.set(letter, '1')
diff --git a/src/shielding/tests/malformed-urls.ts b/src/shielding/tests/malformed-urls.ts
index 9262e707f084..2777e90d6c9f 100644
--- a/src/shielding/tests/malformed-urls.ts
+++ b/src/shielding/tests/malformed-urls.ts
@@ -32,21 +32,19 @@ describe('malformed URLs', () => {
   })
 
   test('allows URLs with control characters (valid UTF-8)', async () => {
+    // %01 decodes fine, so the middleware lets it through.
     const res = await get('/en/test-%01-page')
-    expect(res.statusCode).toBe(404) // Should be 404 since page doesn't exist, not 400
-    // Control characters like %01 are valid UTF-8 and don't cause decoding errors
+    expect(res.statusCode).toBe(404) // 404 because the page does not exist, not 400
   })
 
   test('allows valid URLs with proper encoding', async () => {
     const res = await get('/en/get-started')
     expect(res.statusCode).not.toBe(400)
-    // Should not be blocked by malformed URL middleware
   })
 
   test('allows valid URLs with proper percent encoding', async () => {
     const res = await get('/en/search?q=test%20query')
     expect(res.statusCode).not.toBe(400)
-    // Should not be blocked by malformed URL middleware
   })
 
   test('blocks malformed query parameters', async () => {

From 54ba6bde5ebcccf9a768303a83eb6270d2cba020 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:25:13 +0000
Subject: [PATCH 12/16] Clean up comments in src/ghes-releases (#63274)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/ghes-releases/lib/parse-release-notes.ts  | 40 +++---------
 src/ghes-releases/lib/release-issues.ts       |  3 -
 .../scripts/create-enterprise-issue.ts        |  2 -
 .../scripts/deprecate/rewrite-asset-paths.ts  |  4 --
 .../deprecate/update-automated-pipelines.ts   |  4 +-
 .../scripts/deprecate/update-data.ts          |  8 +--
 .../scripts/generate-release-notes.ts         | 65 +++++--------------
 .../scripts/notify-release-pms.ts             | 30 ++-------
 src/ghes-releases/scripts/release-banner.ts   |  4 --
 .../scripts/update-enterprise-dates.ts        |  1 -
 .../tests/generate-release-notes.ts           | 10 ---
 src/ghes-releases/tests/notify-release-pms.ts |  8 ---
 12 files changed, 37 insertions(+), 142 deletions(-)

diff --git a/src/ghes-releases/lib/parse-release-notes.ts b/src/ghes-releases/lib/parse-release-notes.ts
index 7d47ecf37891..e235430cd314 100644
--- a/src/ghes-releases/lib/parse-release-notes.ts
+++ b/src/ghes-releases/lib/parse-release-notes.ts
@@ -5,22 +5,16 @@
 import fs from 'fs'
 import { load } from 'js-yaml'
 
-// ─── Types ───────────────────────────────────────────────────────────────────
-
 export interface NoteEntry {
   heading: string
   notes: string[]
   sourceUrl: string
 }
 
-// ─── extractYaml ─────────────────────────────────────────────────────────────
-
 /**
- * Extract YAML content from agent output.
  * Looks for ```yaml ... ``` blocks, or falls back to lines starting with "- heading:"
  */
 export function extractYaml(agentOutput: string): string | null {
-  // Try to extract from fenced YAML code block
   const fenced = agentOutput.match(/```ya?ml\s*\n([\s\S]*?)```/)
   if (fenced) return fenced[1].trim()
 
@@ -43,21 +37,11 @@ export function extractYaml(agentOutput: string): string | null {
   return yamlLines.length > 0 ? yamlLines.join('\n').trim() : null
 }
 
-// ─── extractSkipReason ───────────────────────────────────────────────────────
-
-/**
- * Extract a skip reason from YAML that contains `# SKIP: <reason>` followed by `[]`.
- */
 export function extractSkipReason(yamlStr: string): string | null {
   const match = yamlStr.match(/^#\s*SKIP:\s*(.+)/m)
   return match ? match[1].trim() : null
 }
 
-// ─── parseNoteEntries ────────────────────────────────────────────────────────
-
-/**
- * Parse extracted YAML into structured note entries
- */
 export function parseNoteEntries(yamlStr: string, sourceUrl: string): NoteEntry[] {
   const entries: NoteEntry[] = []
 
@@ -82,14 +66,12 @@ export function parseNoteEntries(yamlStr: string, sourceUrl: string): NoteEntry[
       }
     }
   } catch {
-    // YAML parse failed
+    // Malformed YAML returns no entries rather than throwing.
   }
 
   return entries
 }
 
-// ─── loadExistingEntries ─────────────────────────────────────────────────────
-
 /**
  * Parse an existing release notes YAML file and extract NoteEntry[] from it,
  * along with a set of source issue URLs already covered.
@@ -107,7 +89,7 @@ export function loadExistingEntries(yamlPath: string): {
 
 /**
  * Parse release notes YAML content (as a string) and extract NoteEntry[] from it.
- * This is the testable core — no file I/O.
+ * This is the testable core, with no file I/O.
  *
  * Note: This uses manual line-by-line parsing instead of js-yaml because we need
  * to preserve the `# https://github.com/.../issues/NNN` source URL comments that
@@ -168,7 +150,7 @@ export function loadExistingEntriesFromString(content: string): {
       if (currentSection === 'changes') currentHeading = 'Changes'
       else if (currentSection === 'closing_down') currentHeading = 'Closing down'
       else if (currentSection === 'retired') currentHeading = 'Retired'
-      else currentHeading = null // known_issues — skip
+      else currentHeading = null // known_issues: skip
       continue
     }
 
@@ -231,8 +213,6 @@ export function loadExistingEntriesFromString(content: string): {
   return { entries, coveredUrls }
 }
 
-// ─── buildReleaseNotesYaml ───────────────────────────────────────────────────
-
 /**
  * Append YAML lines for a list of note entries at a given indentation level.
  * Handles the `# sourceUrl`, `- |`, and multi-line note content pattern.
@@ -249,9 +229,6 @@ export function appendNoteLines(lines: string[], noteEntries: NoteEntry[], inden
   }
 }
 
-/**
- * Build the final release notes YAML string from note entries.
- */
 export function buildReleaseNotesYaml(
   noteEntries: NoteEntry[],
   releaseCandidate: boolean,
@@ -286,7 +263,7 @@ export function buildReleaseNotesYaml(
 
   lines.push('sections:')
 
-  // ── Features (grouped by heading) ──
+  // Features (grouped by heading).
   const featureEntries = noteEntries.filter((e) => featureHeadings.includes(e.heading))
   const otherEntries = noteEntries.filter((e) => !featureHeadings.includes(e.heading))
 
@@ -294,7 +271,6 @@ export function buildReleaseNotesYaml(
   lines.push('  features:')
 
   if (featureEntries.length > 0) {
-    // Group by heading, preserving template order
     const byHeading = new Map<string, NoteEntry[]>()
     for (const entry of featureEntries) {
       const existing = byHeading.get(entry.heading) || []
@@ -315,7 +291,7 @@ export function buildReleaseNotesYaml(
     lines.push('    # TODO: Add feature notes')
   }
 
-  // ── Changes ──
+  // Changes.
   const changeEntries = otherEntries.filter((e) => !['Closing down', 'Retired'].includes(e.heading))
   if (changeEntries.length > 0) {
     lines.push('')
@@ -323,14 +299,14 @@ export function buildReleaseNotesYaml(
     appendNoteLines(lines, changeEntries, '    ')
   }
 
-  // ── Known issues ──
+  // Known issues.
   lines.push('')
   lines.push('  known_issues:')
   lines.push('    # TODO: Add known issues from "GHES Release Note Tracking" project')
   lines.push('    - |')
   lines.push('      ...')
 
-  // ── Closing down ──
+  // Closing down.
   const closingEntries = otherEntries.filter((e) => e.heading === 'Closing down')
   if (closingEntries.length > 0) {
     lines.push('')
@@ -338,7 +314,7 @@ export function buildReleaseNotesYaml(
     appendNoteLines(lines, closingEntries, '    ')
   }
 
-  // ── Retired ──
+  // Retired.
   const retiredEntries = otherEntries.filter((e) => e.heading === 'Retired')
   if (retiredEntries.length > 0) {
     lines.push('')
diff --git a/src/ghes-releases/lib/release-issues.ts b/src/ghes-releases/lib/release-issues.ts
index dfcb373786b6..91e0d89cb3bd 100644
--- a/src/ghes-releases/lib/release-issues.ts
+++ b/src/ghes-releases/lib/release-issues.ts
@@ -23,9 +23,6 @@ export function parseIssueState(value?: string): IssueState {
   )
 }
 
-/**
- * Build gh CLI args for listing release issues.
- */
 export function buildReleaseIssueListArgs(version: string, issueState: IssueState): string[] {
   const label = `GHES ${version}`
   return [
diff --git a/src/ghes-releases/scripts/create-enterprise-issue.ts b/src/ghes-releases/scripts/create-enterprise-issue.ts
index 99a78b00d1e4..b19db2e4366c 100644
--- a/src/ghes-releases/scripts/create-enterprise-issue.ts
+++ b/src/ghes-releases/scripts/create-enterprise-issue.ts
@@ -99,7 +99,6 @@ async function createDeprecationIssue() {
     return
   }
 
-  // Create the deprecation issue
   const issueTemplate = readFileSync('src/ghes-releases/lib/deprecation-steps.md', 'utf8')
   const { data, content } = matter(issueTemplate)
   const { title, labels } = data
@@ -348,7 +347,6 @@ function getNumberDaysUntilMilestone(milestoneDate: string): number {
   const nextMilestoneDateTime = new Date(milestoneDate).getTime()
   const todayTime = new Date(today).getTime()
   const differenceInMilliseconds = nextMilestoneDateTime - todayTime
-  // Return the difference in days
   return Math.floor(differenceInMilliseconds / (1000 * 60 * 60 * 24))
 }
 
diff --git a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
index a86ff9231f81..0ae4cc3cd8ad 100644
--- a/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
+++ b/src/ghes-releases/scripts/deprecate/rewrite-asset-paths.ts
@@ -28,13 +28,10 @@ export class RewriteAssetPathsPlugin {
     registerAction: (event: string, callback: (args: ResourceSavedArgs) => Promise<void>) => void,
   ) {
     registerAction('onResourceSaved', async ({ resource }: ResourceSavedArgs) => {
-      // Show some activity
       process.stdout.write('.')
 
-      // Only operate on HTML files
       if (!resource.isHtml() && !resource.isCss()) return
 
-      // Get the text contents of the resource
       const text = resource.getText()
       let newBody = text
 
@@ -51,7 +48,6 @@ export class RewriteAssetPathsPlugin {
         newBody = newBody.replace(/<link href=".*manifest.json".*?>/g, '')
 
         if (!this.localDev) {
-          // Rewrite asset paths
           newBody = newBody.replace(
             /(?<attribute>src|href)="(?:\.\.\/|\/)*(?<basepath>_next\/static|javascripts|stylesheets|assets\/fonts|assets\/cb-\d+\/images|node_modules)/g,
             (match: string, attribute: string, basepath: string) => {
diff --git a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
index ca294175a8a9..d1240f2f5d2e 100755
--- a/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
+++ b/src/ghes-releases/scripts/deprecate/update-automated-pipelines.ts
@@ -145,8 +145,8 @@ export async function updateAutomatedPipelines() {
         // Derive the previous release's corresponding directory by replacing
         // the current release number with the previous one. This correctly
         // maps each calendar-date variant to its predecessor, e.g.:
-        //   ghes-3.20-2022-11-28 → ghes-3.19-2022-11-28
-        //   ghes-3.20-2026-03-10 → ghes-3.19-2026-03-10
+        //   ghes-3.20-2022-11-28 -> ghes-3.19-2022-11-28
+        //   ghes-3.20-2026-03-10 -> ghes-3.19-2026-03-10
         const previousDirName = dirToAdd.replace(currentReleaseNumber, previousReleaseNumber)
         if (!existingDataDir.includes(previousDirName)) {
           throw new Error(
diff --git a/src/ghes-releases/scripts/deprecate/update-data.ts b/src/ghes-releases/scripts/deprecate/update-data.ts
index 9c214ec033ce..08e91ce9e9b1 100644
--- a/src/ghes-releases/scripts/deprecate/update-data.ts
+++ b/src/ghes-releases/scripts/deprecate/update-data.ts
@@ -36,7 +36,6 @@ export function updateDataFiles() {
 function updateReusableData() {
   const deletedDataFiles = []
 
-  // Remove empty reusables
   for (const file of dataReusables) {
     const oldContents = fs.readFileSync(file, 'utf8').trim()
     if (oldContents === '') {
@@ -71,10 +70,9 @@ function updateReusableData() {
   }
 }
 
-// Removes deprecated data/feature files and outputs a list
-// of data/features available in all versions - this list
-// is currently only used used for reviewing purposes when
-// deprecating a GHES release
+// Removes deprecated data/feature files and outputs a list of data/features
+// available in all versions. That list is only used for review during a GHES
+// deprecation.
 function updateFeatureData() {
   const allFeatureFiles = new Set()
 
diff --git a/src/ghes-releases/scripts/generate-release-notes.ts b/src/ghes-releases/scripts/generate-release-notes.ts
index d5b30a3c35be..1ecdd3ab3b21 100644
--- a/src/ghes-releases/scripts/generate-release-notes.ts
+++ b/src/ghes-releases/scripts/generate-release-notes.ts
@@ -32,7 +32,6 @@ import {
   parseIssueState,
 } from '@/ghes-releases/lib/release-issues'
 
-// ─── Ctrl+C handling ─────────────────────────────────────────────────────────
 // Copilot CLI puts the terminal in raw mode, so we catch Ctrl+C (0x03) manually.
 
 let activeChild: ChildProcess | null = null
@@ -56,8 +55,6 @@ if (process.stdin.isTTY) {
   })
 }
 
-// ─── Types ───────────────────────────────────────────────────────────────────
-
 interface ReleaseIssue {
   number: number
   title: string
@@ -83,8 +80,6 @@ function loadFeatureHeadings(): string[] {
   return _featureHeadingsCache
 }
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
 /**
  * Run `gh` CLI commands with native auth (no GITHUB_TOKEN interference)
  */
@@ -99,9 +94,6 @@ function gh(args: string[]): string {
   })
 }
 
-/**
- * Fetch release issues labeled "GHES <version>" using the selected issue state.
- */
 function fetchReleaseIssues(version: string, issueState: IssueState): ReleaseIssue[] {
   const output = gh(buildReleaseIssueListArgs(version, issueState))
   const issues = JSON.parse(output) as ReleaseIssue[]
@@ -123,9 +115,6 @@ function extractChangelogPrUrl(issueBody: string): string | null {
   return match ? match[0] : null
 }
 
-/**
- * Fetch the body of a changelog PR by URL.
- */
 function fetchChangelogPrBody(prUrl: string): string | null {
   try {
     const output = gh(['pr', 'view', prUrl, '--json', 'body'])
@@ -176,7 +165,7 @@ function searchChangelogPr(issueNumber: number): ChangelogInfo | null {
       }
     }
   } catch {
-    // Search failed — fall back to no changelog
+    // Search failed, so fall back to no changelog.
   }
   return null
 }
@@ -195,23 +184,20 @@ function findChangelogPr(issue: ReleaseIssue): ChangelogInfo | null {
 }
 
 /**
- * Resolve the Copilot CLI path. Checks common locations.
+ * Resolve the Copilot CLI path.
  * Result is cached after first call.
  */
 let _copilotCliPath: string | null = null
 function findCopilotCli(): string {
   if (_copilotCliPath) return _copilotCliPath
 
-  // Check if `copilot` is on PATH
   try {
     const result = execFileSync('which', ['copilot'], { encoding: 'utf8' }).trim()
     if (result) {
       _copilotCliPath = result
       return result
     }
-  } catch {
-    // not on PATH
-  }
+  } catch {}
 
   // Fallback: check VS Code extension storage locations.
   // These paths are macOS-only. On Linux/Windows the `which` check above should
@@ -227,7 +213,6 @@ function findCopilotCli(): string {
     return vsCodePath
   }
 
-  // Check VS Code stable location (macOS)
   const vsCodeStablePath = path.join(
     homeDir,
     'Library/Application Support/Code/User/globalStorage/github.copilot-chat/copilotCli/copilot',
@@ -382,9 +367,6 @@ function runAgent(ctx: AgentContext): Promise<string> {
   })
 }
 
-/**
- * Sleep for the given number of milliseconds (non-blocking).
- */
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
@@ -401,7 +383,7 @@ interface AgentResult {
  * Run the agent with retry logic. Retries up to `maxRetries` times on failure.
  * Validates that extracted YAML parses into non-empty entries before accepting.
  * If the agent tries to skip (returns `# SKIP: reason` + `[]`), treats it as a
- * failed attempt and retries — issues that matched the GHES label filter should
+ * failed attempt and retries, because issues that matched the GHES label filter should
  * always get a release note. If all attempts result in skips, the last skip
  * reason is attached as a warning.
  */
@@ -425,9 +407,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
         if (skipReason) {
           lastSkipReason = skipReason
           lastError = new Error(`Agent tried to skip: ${skipReason}`)
-          // Fall through to retry
         } else {
-          // Validate that the YAML actually contains usable entries
           const testEntries = parseNoteEntries(yamlStr, ctx.issueUrl)
           if (testEntries.length > 0) {
             return {
@@ -438,7 +418,7 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
               skipWarning: lastSkipReason ?? undefined,
             }
           }
-          // YAML was extracted but empty/unparseable — retry
+          // YAML was extracted but is empty or unparseable, so retry.
           lastError = new Error(
             `Agent returned YAML but it contained no valid entries (got: ${yamlStr.substring(0, 80)})`,
           )
@@ -449,19 +429,15 @@ async function runAgentWithRetry(ctx: AgentContext, maxRetries = 2): Promise<Age
     } catch (error) {
       lastError = error as Error
     }
-    // Brief delay before retry
     if (attempt <= maxRetries) {
       await sleep(3000)
     }
   }
-  // Attach raw output to the error for debugging
   const err = lastError || new Error('Agent failed after retries')
   ;(err as Error & { rawOutput?: string }).rawOutput = lastRawOutput
   throw err
 }
 
-// ─── CLI ─────────────────────────────────────────────────────────────────────
-
 const program = new Command()
 
 program
@@ -520,7 +496,7 @@ program
         process.exit(1)
       }
 
-      // ── Prerequisite checks ──
+      // Prerequisite checks.
       try {
         execFileSync('gh', ['--version'], { stdio: 'ignore' })
       } catch {
@@ -541,7 +517,6 @@ program
         process.exit(1)
       }
 
-      // Validate release version format
       if (!/^\d+\.\d+$/.test(release)) {
         console.error(
           `Error: Invalid release version format "${release}". Expected: X.Y (e.g., 3.20)`,
@@ -549,11 +524,11 @@ program
         process.exit(1)
       }
 
-      // ── Step 1: Fetch release issues ──
+      // Step 1: Fetch release issues.
       let issues: ReleaseIssue[]
 
       if (singleIssue) {
-        // For a single issue, fetch it directly — no need to list all issues
+        // For a single issue, fetch it directly rather than listing all issues.
         spinner.start(`Fetching issue #${singleIssue}...`)
         try {
           const output = gh([
@@ -595,11 +570,10 @@ program
           process.exit(0)
         }
 
-        // Filter out GA meta-issues (e.g., "GHES 3.20 GA [GA]") — these are tracking issues, not features
+        // GA meta-issues (e.g. "GHES 3.20 GA [GA]") are tracking issues, not features.
         const originalCount = issues.length
         issues = issues.filter((issue) => {
           const title = issue.title.trim()
-          // Strip all trailing label tags like [GA], [Public Preview], etc.
           const stripped = title.replace(/\s*\[[^\]]*\]/g, '').trim()
           // Skip issues whose title is just "GHES X.Y GA" or "GHES X.Y release"
           if (/^ghes\s+\d+\.\d+\s+ga$/i.test(stripped)) return false
@@ -611,7 +585,7 @@ program
           console.log(`  Filtered out ${filteredCount} meta-issue(s) (GA/release tracking)`)
         }
 
-        // Filter out [Private Preview] issues — these never get release notes
+        // [Private Preview] issues never get release notes.
         const beforePrivateFilter = issues.length
         issues = issues.filter((issue) => {
           return !/\[Private Preview\]/i.test(issue.title)
@@ -623,7 +597,7 @@ program
           )
         }
 
-        // Filter out issues labeled "internal release" — these are internal-only and don't get release notes
+        // "internal release" issues are internal-only and get no release notes.
         const beforeInternalFilter = issues.length
         issues = issues.filter((issue) => {
           return !issue.labels.some((l) => l.name.toLowerCase() === 'internal release')
@@ -634,13 +608,12 @@ program
         }
       }
 
-      // Compute output path upfront so we can check for existing file
       const dirName = release.replace('.', '-')
       const fileName = rc ? '0-rc1.yml' : '0.yml'
       const outputDir = path.join(process.cwd(), 'data/release-notes/enterprise-server', dirName)
       const outputPath = path.join(outputDir, fileName)
 
-      // ── Incremental mode: load existing entries ──
+      // Incremental mode: load existing entries.
       const allEntries: NoteEntry[] = []
       let existingCoveredUrls = new Set<string>()
 
@@ -679,7 +652,7 @@ program
         }
       }
 
-      // ── Step 2: Find changelog PRs ──
+      // Step 2: Find changelog PRs.
       spinner.start('Finding changelog PRs...')
       const issueChangelogMap = new Map<number, ChangelogInfo | null>()
       let changelogFound = 0
@@ -691,11 +664,11 @@ program
       }
       spinner.succeed(`Found changelog PRs for ${changelogFound}/${issues.length} issues`)
 
-      // ── Step 3: Run agent on each issue ──
+      // Step 3: Run agent on each issue.
       const failures: { issue: ReleaseIssue; error: string }[] = []
       const existingEntryCount = allEntries.length
 
-      // Load valid headings once (cached, but clearer when hoisted)
+      // Hoisted for clarity. The underlying load is already cached.
       const featureHeadings = loadFeatureHeadings()
 
       // Helper to write current entries to file (called after each success and on Ctrl+C)
@@ -712,7 +685,6 @@ program
         }
       }
 
-      // Register so Ctrl+C saves progress
       flushBeforeExit = writeCurrentOutput
 
       for (let i = 0; i < issues.length; i++) {
@@ -779,7 +751,6 @@ program
           spinner.suffixText = ''
           spinner.succeed(`${label}${retryNote}`)
 
-          // Write incrementally so progress is saved
           writeCurrentOutput()
         } catch (error) {
           const err = error as Error & { rawOutput?: string }
@@ -788,7 +759,7 @@ program
           failures.push({ issue, error: msg })
           spinner.suffixText = ''
           if (isSkipFailure) {
-            // Clean output for skip failures — no raw agent dump
+            // Skip failures get clean output, with no raw agent dump.
             const skipReason = msg.replace('Agent tried to skip: ', '')
             spinner.warn(`${label} — skipped by agent`)
             console.log(`    Reason: ${skipReason}`)
@@ -808,7 +779,7 @@ program
         }
       }
 
-      // ── Step 4: Final summary ──
+      // Step 4: Final summary.
       flushBeforeExit = null
       const newCount = allEntries.length - existingEntryCount
       if (existingEntryCount > 0) {
@@ -827,7 +798,7 @@ program
 
       if (stdout) {
         if (failures.length > 0 && allEntries.length === 0) {
-          // All issues failed — don't print empty template
+          // All issues failed, so don't print an empty template.
           process.exit(1)
         }
         if (singleIssue) {
diff --git a/src/ghes-releases/scripts/notify-release-pms.ts b/src/ghes-releases/scripts/notify-release-pms.ts
index 446de67a46af..79adb25aad38 100644
--- a/src/ghes-releases/scripts/notify-release-pms.ts
+++ b/src/ghes-releases/scripts/notify-release-pms.ts
@@ -22,15 +22,11 @@ import fs from 'fs'
 import path from 'path'
 import ora from 'ora'
 
-// ─── Types ───────────────────────────────────────────────────────────────────
-
 export interface SourceNote {
   issueUrl: string
   issueNumber: number
 }
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
 /**
  * Run read-only `gh` CLI commands.
  * Uses DOCS_BOT_PAT_BASE when available (CI), otherwise falls back to
@@ -90,8 +86,8 @@ export function parseSourceNotes(content: string): SourceNote[] {
     const match = lines[i].match(/^\s*#\s*(https:\/\/github\.com\/github\/releases\/issues\/(\d+))/)
     if (match) {
       const issueNumber = parseInt(match[2], 10)
-      // Deduplicate — some issues appear multiple times (e.g., in features + changes)
-      // We use the first occurrence so the link points to the primary note
+      // Some issues appear multiple times (e.g. in features and changes). Keep the
+      // first occurrence so the link points to the primary note.
       if (!seen.has(issueNumber)) {
         seen.add(issueNumber)
         notes.push({
@@ -105,17 +101,11 @@ export function parseSourceNotes(content: string): SourceNote[] {
   return notes
 }
 
-/**
- * Read a release notes YAML file and extract source issue URLs.
- */
 function extractSourceNotes(yamlPath: string): SourceNote[] {
   const content = fs.readFileSync(yamlPath, 'utf8')
   return parseSourceNotes(content)
 }
 
-/**
- * Build the comment body for a release issue notification.
- */
 export function buildCommentBody(
   version: string,
   rc: boolean,
@@ -142,15 +132,10 @@ You're welcome to edit it in the PR. If you do nothing, the note will be publish
 Any questions, ask in [#docs-ghes-releases](https://github-grid.enterprise.slack.com/archives/C0AQ37XBK7D).`
 }
 
-/**
- * Build the marker string used to identify notification comments.
- */
 export function buildMarker(version: string, releaseType: 'rc' | 'ga'): string {
   return `<!-- ghes-release-note-review: ${version}-${releaseType} -->`
 }
 
-// ─── CLI ─────────────────────────────────────────────────────────────────────
-
 const program = new Command()
 
 program
@@ -186,7 +171,6 @@ program
       const { release, pr: prNumber, dryRun, reviewDate } = options
       const spinner = ora()
 
-      // Validate --review-date format if provided
       if (reviewDate && !/^\d{4}-\d{2}-\d{2}$/.test(reviewDate)) {
         console.error(
           `Error: Invalid date format "${reviewDate}". Expected: YYYY-MM-DD (e.g., 2026-04-20)`,
@@ -194,7 +178,6 @@ program
         process.exit(1)
       }
 
-      // Validate release version format
       if (!/^\d+\.\d+$/.test(release)) {
         console.error(
           `Error: Invalid release version format "${release}". Expected: X.Y (e.g., 3.20)`,
@@ -202,7 +185,6 @@ program
         process.exit(1)
       }
 
-      // Determine RC vs GA
       const dirName = release.replace('.', '-')
       const rcPath = path.join(
         process.cwd(),
@@ -257,7 +239,7 @@ program
 
       const relativeFilePath = path.relative(process.cwd(), yamlPath)
 
-      // ── Step 1: Extract source issue URLs ──
+      // Step 1: Extract source issue URLs.
       spinner.start('Parsing release notes file...')
       const sourceNotes = extractSourceNotes(yamlPath)
       spinner.succeed(`Found ${sourceNotes.length} unique release issue(s) in ${relativeFilePath}`)
@@ -267,7 +249,7 @@ program
         process.exit(0)
       }
 
-      // ── Step 2: Check for existing comments (avoid duplicates) ──
+      // Step 2: Check for existing comments (avoid duplicates).
       const releaseType = rc ? 'rc' : 'ga'
       const marker = buildMarker(release, releaseType)
       const alreadyCommented = new Set<number>()
@@ -300,7 +282,7 @@ program
         spinner.succeed('No existing notifications found')
       }
 
-      // ── Step 3: Post comments ──
+      // Step 3: Post comments.
       const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))
 
       if (toNotify.length === 0) {
@@ -360,7 +342,7 @@ program
         }
       }
 
-      // ── Summary ──
+      // Summary.
       console.log(`\n${'─'.repeat(40)}`)
       console.log(`${dryRun ? '🔍 Dry run' : '✅ Done'}`)
       console.log(
diff --git a/src/ghes-releases/scripts/release-banner.ts b/src/ghes-releases/scripts/release-banner.ts
index abbd36fd15a0..7c2136cb64b4 100644
--- a/src/ghes-releases/scripts/release-banner.ts
+++ b/src/ghes-releases/scripts/release-banner.ts
@@ -41,7 +41,6 @@ if (!Object.keys(allVersions).includes(options.version)) {
   process.exit(1)
 }
 
-// Load the release candidate variable
 async function main(): Promise<void> {
   let jsCode = await fs.readFile(releaseCandidateJSFile, 'utf8')
   const lineRegex = /export const releaseCandidate = .*/
@@ -51,7 +50,6 @@ async function main(): Promise<void> {
     )
   }
 
-  // Create or remove the variable
   if (options.action === 'create') {
     jsCode = jsCode.replace(
       lineRegex,
@@ -61,10 +59,8 @@ async function main(): Promise<void> {
     jsCode = jsCode.replace(lineRegex, `export const releaseCandidate = null`)
   }
 
-  // Update the file
   await fs.writeFile(releaseCandidateJSFile, jsCode)
 
-  // Display next steps
   console.log(`\nDone! Commit the update to ${releaseCandidateJSFile}. This ${options.action}s the banner for ${options.version}.
 
 - To change the banner text, you can edit header.notices.release_candidate in data/ui.yml.
diff --git a/src/ghes-releases/scripts/update-enterprise-dates.ts b/src/ghes-releases/scripts/update-enterprise-dates.ts
index 8387b60cad30..2eff3bc7c721 100644
--- a/src/ghes-releases/scripts/update-enterprise-dates.ts
+++ b/src/ghes-releases/scripts/update-enterprise-dates.ts
@@ -44,7 +44,6 @@ if (!process.env.GITHUB_TOKEN) {
 main()
 
 async function main(): Promise<void> {
-  // send owner, repo, ref, path
   let rawDates: RawReleaseData = {}
   try {
     rawDates = JSON.parse(
diff --git a/src/ghes-releases/tests/generate-release-notes.ts b/src/ghes-releases/tests/generate-release-notes.ts
index 4082ee2a77ca..a656f6d0125d 100644
--- a/src/ghes-releases/tests/generate-release-notes.ts
+++ b/src/ghes-releases/tests/generate-release-notes.ts
@@ -8,8 +8,6 @@ import {
   buildReleaseNotesYaml,
 } from '@/ghes-releases/lib/parse-release-notes'
 
-// ─── extractYaml ─────────────────────────────────────────────────────────────
-
 describe('extractYaml', () => {
   test('extracts YAML from a fenced code block', () => {
     const input = `Here is the release note:
@@ -46,8 +44,6 @@ Some trailing text that is not YAML`
   })
 })
 
-// ─── extractSkipReason ───────────────────────────────────────────────────────
-
 describe('extractSkipReason', () => {
   test('extracts reason from "# SKIP: <reason>"', () => {
     expect(extractSkipReason('# SKIP: Not applicable to GHES')).toBe('Not applicable to GHES')
@@ -58,8 +54,6 @@ describe('extractSkipReason', () => {
   })
 })
 
-// ─── parseNoteEntries ────────────────────────────────────────────────────────
-
 describe('parseNoteEntries', () => {
   const sourceUrl = 'https://github.com/github/releases/issues/1234'
 
@@ -108,8 +102,6 @@ describe('parseNoteEntries', () => {
   })
 })
 
-// ─── loadExistingEntriesFromString ───────────────────────────────────────────
-
 describe('loadExistingEntriesFromString', () => {
   test('parses feature entries with source URL comments', () => {
     const content = `date: '2025-01-15'
@@ -264,8 +256,6 @@ sections:
   })
 })
 
-// ─── buildReleaseNotesYaml ───────────────────────────────────────────────────
-
 describe('buildReleaseNotesYaml', () => {
   const featureHeadings = ['GitHub Actions', 'Repositories', 'APIs']
 
diff --git a/src/ghes-releases/tests/notify-release-pms.ts b/src/ghes-releases/tests/notify-release-pms.ts
index affefe38c49d..d9e87a09cd8f 100644
--- a/src/ghes-releases/tests/notify-release-pms.ts
+++ b/src/ghes-releases/tests/notify-release-pms.ts
@@ -7,8 +7,6 @@ import {
 } from '@/ghes-releases/scripts/notify-release-pms'
 import type { SourceNote } from '@/ghes-releases/scripts/notify-release-pms'
 
-// ─── parseSourceNotes ────────────────────────────────────────────────────────
-
 describe('parseSourceNotes', () => {
   test('extracts issue URLs from YAML comments', () => {
     const content = `date: '2026-04-01'
@@ -67,8 +65,6 @@ sections:
   })
 })
 
-// ─── buildMarker ─────────────────────────────────────────────────────────────
-
 describe('buildMarker', () => {
   test('produces a stable HTML comment marker for RC', () => {
     expect(buildMarker('3.21', 'rc')).toBe('<!-- ghes-release-note-review: 3.21-rc -->')
@@ -83,8 +79,6 @@ describe('buildMarker', () => {
   })
 })
 
-// ─── buildCommentBody ────────────────────────────────────────────────────────
-
 describe('buildCommentBody', () => {
   test('includes the marker in the comment body', () => {
     const body = buildCommentBody('3.21', true, 100, ['octocat'])
@@ -105,8 +99,6 @@ describe('buildCommentBody', () => {
   })
 })
 
-// ─── Duplicate-prevention logic ──────────────────────────────────────────────
-
 describe('duplicate-prevention filtering', () => {
   // This tests the core filtering logic used in the CLI action:
   //   const toNotify = sourceNotes.filter((n) => !alreadyCommented.has(n.issueNumber))

From f65fee93f62467a9621e1a61183b39bb925324e9 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:32:54 +0000
Subject: [PATCH 13/16] Clean up code comments in src/observability source
 files (#63229)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
Copilot-Session: c7ae285a-5311-4fe6-a3d3-093869aa5d4e
---
 src/observability/lib/failbot.ts              | 20 +++-------
 .../lib/handle-package-not-found.ts           |  2 +-
 src/observability/lib/runtime-metrics.ts      | 14 ++-----
 src/observability/lib/statsd.ts               | 11 ++----
 src/observability/lib/to-error.ts             |  3 +-
 src/observability/lib/tracing.browser.ts      |  2 +-
 src/observability/lib/tracing.ts              | 23 +++++------
 src/observability/logger/index.ts             | 38 +++----------------
 src/observability/logger/lib/log-levels.ts    | 13 +++----
 .../logger/lib/logger-context.ts              | 11 ++----
 src/observability/logger/lib/pod-identity.ts  |  4 +-
 src/observability/logger/lib/to-logfmt.ts     | 12 +-----
 .../get-automatic-request-logger.ts           | 23 ++---------
 .../middleware/catch-middleware-error.ts      |  1 -
 src/observability/middleware/handle-errors.ts | 34 ++++++-----------
 15 files changed, 58 insertions(+), 153 deletions(-)

diff --git a/src/observability/lib/failbot.ts b/src/observability/lib/failbot.ts
index 226def0ae62d..e2b90878c26e 100644
--- a/src/observability/lib/failbot.ts
+++ b/src/observability/lib/failbot.ts
@@ -4,13 +4,11 @@ import { getLoggerContext } from '@/observability/logger/lib/logger-context'
 
 const HAYSTACK_APP = 'docs'
 
+// Five attempts at a 3000ms timeout, with backoff delays of 1, 2, 4, and 8 seconds,
+// bound a failing report at roughly 30 seconds.
 async function retryingFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
   const url = typeof input === 'string' ? input : input.toString()
 
-  // Use fetchWithRetry with retry configuration matching got's behavior
-  // With the timeout at 3000 (milliseconds) and the retry.limit
-  // at 4 (times), the total worst-case is:
-  // 3000 * 4  + 1000 + 2000 + 3000 + 4000 + 8000 = 30 seconds
   const response = await fetchWithRetry(
     url,
     {
@@ -29,7 +27,6 @@ async function retryingFetch(input: RequestInfo | URL, init?: RequestInit): Prom
 }
 
 export function report(error: Error, metadata?: Record<string, unknown>) {
-  // If there's no HAYSTACK_URL set, bail early
   if (!process.env.HAYSTACK_URL) {
     return
   }
@@ -45,9 +42,9 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
     backends,
   })
 
-  // Add the request id from the logger context to the metadata
-  // Per https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
-  // Metadata can only be a flat object with string & number values, so only add the requestUuid
+  // Metadata can only be a flat object with string & number values,
+  // so only add the requestUuid.
+  // https://github.com/github/failbotg/blob/main/docs/api.md#additional-data
   const loggerContext = getLoggerContext()
 
   return failbot.report(error, {
@@ -56,12 +53,7 @@ export function report(error: Error, metadata?: Record<string, unknown>) {
   })
 }
 
-// Kept for legacy so you can continue to do:
-//
-//  import FailBot from './lib/failbot'
-//  ...
-//  FailBot.report(myError)
-//
+// Kept so legacy callers can keep doing `FailBot.report(myError)`.
 export default {
   report,
 }
diff --git a/src/observability/lib/handle-package-not-found.ts b/src/observability/lib/handle-package-not-found.ts
index 2476b21f2d4c..8bb738532c08 100644
--- a/src/observability/lib/handle-package-not-found.ts
+++ b/src/observability/lib/handle-package-not-found.ts
@@ -4,7 +4,7 @@ to prompt the contributor to run `npm ci`.
 This handler must be separate from handle-exceptions.ts in order to function.
 It's imported in package.json in nodemonConfig,
 whereas that is imported in start-server.ts.
-This file should not import any packages.
+This file must not import any packages.
 We are suggesting `npm ci` to contributors
 to avoid unexpected changes to the package-lock.json file.
 All other errors should fall through to the error handler in handle-exceptions.ts.
diff --git a/src/observability/lib/runtime-metrics.ts b/src/observability/lib/runtime-metrics.ts
index 3ab894cf3e52..42740357f5af 100644
--- a/src/observability/lib/runtime-metrics.ts
+++ b/src/observability/lib/runtime-metrics.ts
@@ -2,9 +2,9 @@
  * Periodically emits Node.js runtime metrics to Datadog via StatsD.
  *
  * Covers three categories that are otherwise invisible:
- *  1. V8 heap — used vs limit, so we can spot memory pressure before OOMs.
- *  2. GC — pause duration, so we can correlate latency spikes with GC.
- *  3. Event-loop delay — p50/p99, so we can see when the loop is blocked.
+ *  1. V8 heap: used vs limit, so we can spot memory pressure before OOMs.
+ *  2. GC: pause duration, so we can correlate latency spikes with GC.
+ *  3. Event-loop delay: p50/p99, so we can see when the loop is blocked.
  *
  * Only activates when StatsD is sending real metrics (MODA_PROD_SERVICE_ENV).
  */
@@ -23,7 +23,6 @@ function isMetricsEnabled(): boolean {
 
 /**
  * Call once at server start. Safe to call multiple times (no-op after first).
- * Only starts collection when StatsD is sending real metrics.
  */
 export function startRuntimeMetrics(): void {
   if (started) return
@@ -31,19 +30,16 @@ export function startRuntimeMetrics(): void {
 
   if (!isMetricsEnabled()) return
 
-  // --- V8 heap stats (sampled on an interval) ---
   setInterval(() => {
     const heap = v8.getHeapStatistics()
     statsd.gauge('node.heap.used', heap.used_heap_size)
     statsd.gauge('node.heap.total', heap.total_heap_size)
     statsd.gauge('node.heap.limit', heap.heap_size_limit)
     statsd.gauge('node.heap.external', heap.external_memory)
-    // Percentage of heap limit currently in use
     const pct = heap.heap_size_limit > 0 ? (heap.used_heap_size / heap.heap_size_limit) * 100 : 0
     statsd.gauge('node.heap.used_pct', pct)
   }, INTERVAL_MS).unref()
 
-  // --- GC pause durations ---
   const gcObserver = new PerformanceObserver((list) => {
     for (const entry of list.getEntries()) {
       const kind = (entry as unknown as { detail?: { kind?: number } }).detail?.kind
@@ -55,7 +51,6 @@ export function startRuntimeMetrics(): void {
   })
   gcObserver.observe({ entryTypes: ['gc'] })
 
-  // --- Event-loop delay (histogram sampled every 20 ms) ---
   const eld = monitorEventLoopDelay({ resolution: 20 })
   eld.enable()
 
@@ -68,9 +63,6 @@ export function startRuntimeMetrics(): void {
   }, INTERVAL_MS).unref()
 }
 
-/**
- * Reset the started flag. Only for use in tests.
- */
 export function _resetForTesting(): void {
   started = false
 }
diff --git a/src/observability/lib/statsd.ts b/src/observability/lib/statsd.ts
index 117d5cb6269b..ff8254d18ffe 100644
--- a/src/observability/lib/statsd.ts
+++ b/src/observability/lib/statsd.ts
@@ -18,13 +18,10 @@ const tagCandidates = ['app:docs', modaApp]
 export const tags: string[] = tagCandidates.filter((tag): tag is string => Boolean(tag))
 
 const statsd = new StatsD({
-  // When host and port are not set, hot-shots will default to the
-  // DD_AGENT_HOST and DD_DOGSTATSD_PORT environment variables.
-  // If undefined, the host will default to 'localhost' and the port
-  // will default to 8125.
-  // Moda configuration defines DD_DOGSTATSD_PORT but not DD_AGENT_HOST.
-  // For Moda, the host must be set to the Kubernetes node name, which is
-  // set in KUBE_NODE_HOSTNAME.
+  // hot-shots falls back to DD_AGENT_HOST and DD_DOGSTATSD_PORT,
+  // then to localhost:8125.
+  // Moda defines DD_DOGSTATSD_PORT but not DD_AGENT_HOST,
+  // and needs the host set to the Kubernetes node name from KUBE_NODE_HOSTNAME.
   host: DD_AGENT_HOST || KUBE_NODE_HOSTNAME,
   port: DD_DOGSTATSD_PORT ? parseInt(DD_DOGSTATSD_PORT, 10) : undefined,
   prefix: 'docs.',
diff --git a/src/observability/lib/to-error.ts b/src/observability/lib/to-error.ts
index 19f7e551b1e5..583b66e5fbd8 100644
--- a/src/observability/lib/to-error.ts
+++ b/src/observability/lib/to-error.ts
@@ -1,5 +1,4 @@
-// Safely convert an unknown thrown value to an Error, avoiding JSON.stringify
-// which can throw on circular references.
+// JSON.stringify can throw on circular references, so fall back to String().
 export function toError(value: Error | unknown): Error {
   if (value instanceof Error) return value
   try {
diff --git a/src/observability/lib/tracing.browser.ts b/src/observability/lib/tracing.browser.ts
index 847629fc1ff8..c9413916387a 100644
--- a/src/observability/lib/tracing.browser.ts
+++ b/src/observability/lib/tracing.browser.ts
@@ -1,3 +1,3 @@
-// Browser stub for tracing.ts — OTel is server-only.
+// Browser stub for tracing.ts: OTel is server-only.
 // This file is aliased in by Next.js webpack and Turbopack for client bundles.
 // It's a no-op: tracing.ts is a side-effect-only module with no exports.
diff --git a/src/observability/lib/tracing.ts b/src/observability/lib/tracing.ts
index e14f29b859e6..91f4e9ecb874 100644
--- a/src/observability/lib/tracing.ts
+++ b/src/observability/lib/tracing.ts
@@ -1,16 +1,14 @@
-// OpenTelemetry distributed tracing setup for docs-internal.
+// OpenTelemetry distributed tracing setup for docs-internal,
+// following the same pattern as github/alloy and github/github-ui.
 //
-// Follows the same pattern as github/alloy and github/github-ui:
-//   - Conditional on OTEL_EXPORTER_OTLP_TRACES_ENDPOINT being set
-//   - OTLP/HTTP (proto) exporter to OTel Collector mesh
-//   - W3C Trace Context + Baggage propagation
-//   - Explicit instrumentation list (HTTP, Express, Undici/fetch) instead of
-//     `getNodeAutoInstrumentations()`. The "auto" helper enables ~30
-//     instrumentations including ones that patch Node core modules
-//     (`fs`, `net`, `dns`) on every server. Several of these are known to
-//     cause performance and listener-leak issues — OTel itself recommends
-//     disabling `instrumentation-fs` in production. We only have HTTP traffic
-//     and outbound fetch in this app, so we wire those up explicitly.
+// The instrumentation list (HTTP, Express, Undici/fetch) is explicit
+// instead of `getNodeAutoInstrumentations()`.
+// The "auto" helper enables ~30 instrumentations,
+// including ones that patch Node core modules (`fs`, `net`, `dns`) on every server.
+// Several of these are known to cause performance and listener-leak issues,
+// and OTel itself recommends disabling `instrumentation-fs` in production.
+// We only have HTTP traffic and outbound fetch in this app,
+// so we wire those up explicitly.
 //
 // References:
 //   - https://thehub.github.com/epd/engineering/dev-practicals/observability/distributed-tracing/
@@ -53,7 +51,6 @@ if (process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) {
     })
   }
 
-  // Gracefully shut down the SDK on process exit.
   // Uses `once` to prevent duplicate shutdown if SIGTERM is delivered multiple times.
   process.once('SIGTERM', async () => {
     try {
diff --git a/src/observability/logger/index.ts b/src/observability/logger/index.ts
index 9e115207c3dc..3495a799c2d0 100644
--- a/src/observability/logger/index.ts
+++ b/src/observability/logger/index.ts
@@ -25,7 +25,6 @@ function formatTimestamp(): string {
   return `${h}:${m}:${s}.${ms}`
 }
 
-// Format non-error included context as compact key=value pairs
 function formatContext(ctx: Record<string, unknown>): string {
   const parts: string[] = []
   for (const [key, value] of Object.entries(ctx)) {
@@ -46,7 +45,6 @@ function formatContext(ctx: Record<string, unknown>): string {
   return parts.length > 0 ? `  ${parts.join(' ')}` : ''
 }
 
-// Safely resolve filePath to a relative path.
 // Handles file:// URLs (from import.meta.url) and plain string labels.
 function resolveFilePath(filePath: string): string {
   try {
@@ -63,27 +61,18 @@ type IncludeContext = { [key: string]: unknown }
 // BUILD_SHA is baked into each Docker image via ARG/ENV in the Dockerfile.
 const BUILD_SHA = process.env.BUILD_SHA || undefined
 
-// Type definitions for logger methods with overloads
+// A trailing plain object is treated as extra context, not a message part.
+// Error arguments are extracted from anywhere in the list,
+// and their messages appended to the log message.
 interface LoggerMethod {
-  // Pattern 1: Just a message e.g. `logger.info('Hello world')`
   (message: string): void
-  // Pattern 2: Message with extraData object e.g. `logger.info('Hello world', { userId: 123 })`
   (message: string, extraData: IncludeContext): void
-  // Pattern 3: Multiple message parts e.g. `logger.info('Hello', 'world', 123, true)`
   (message: string, ...messageParts: (string | number | boolean)[]): void
-  // Pattern 4: Multiple message parts followed by extraData object e.g.
-  // `logger.info('Hello', 'world', 123, true, { userId: 123 })`
-  // Note: The extraData object must be the last argument
   (
     message: string,
     ...args: [...messageParts: (string | number | boolean)[], extraData: IncludeContext]
   ): void
-  // Pattern 5: Message with Error object (automatically handled) e.g.
-  // `logger.error('Database error', error)`
-  // Note: This will append the error message to the final log message
   (message: string, error: Error): void
-  // Pattern 6: Message with multiple parts and Error objects
-  // e.g. `logger.error('Multiple failures', error1, error2)`
   (message: string, ...args: (string | number | boolean | Error | IncludeContext | object)[]): void
 }
 
@@ -99,7 +88,6 @@ export function createLogger(filePath: string) {
     throw new Error('createLogger must be called with the import.meta.url argument')
   }
 
-  // Helper function to check if a value is a plain object (not Array, Error, Date, etc.)
   function isPlainObject(value: unknown): value is Record<string, unknown> {
     return (
       value !== null &&
@@ -111,13 +99,10 @@ export function createLogger(filePath: string) {
     )
   }
 
-  // The actual log function used by each level-specific method.
   function logMessage(level: keyof typeof LOG_LEVELS, message: string, ...args: unknown[]) {
-    // Determine if we have extraData or additional message parts
     let finalMessage: string
     let includeContext: IncludeContext = {}
 
-    // First, extract any Error objects from the arguments and handle them specially
     const errorObjects: Error[] = []
     const nonErrorArgs: unknown[] = []
 
@@ -129,42 +114,33 @@ export function createLogger(filePath: string) {
       }
     }
 
-    // Handle the non-error arguments for message building and extraData
     if (nonErrorArgs.length > 0 && isPlainObject(nonErrorArgs[nonErrorArgs.length - 1])) {
-      // Last non-error argument is a plain object - treat as extraData
       includeContext = { ...(nonErrorArgs[nonErrorArgs.length - 1] as IncludeContext) }
       const messageParts = nonErrorArgs.slice(0, -1)
       if (messageParts.length > 0) {
-        // There are message parts before the extraData object
         const allMessageParts = [
           message,
           ...messageParts.map((arg) => (typeof arg === 'string' ? arg : String(arg))),
         ]
         finalMessage = allMessageParts.join(' ')
       } else {
-        // Only the extraData object, no additional message parts
         finalMessage = message
       }
     } else if (nonErrorArgs.length > 0) {
-      // Multiple arguments or non-plain-object - concatenate as message parts
       const allMessageParts = [
         message,
         ...nonErrorArgs.map((arg) => (typeof arg === 'string' ? arg : String(arg))),
       ]
       finalMessage = allMessageParts.join(' ')
     } else {
-      // No additional non-error arguments
       finalMessage = message
     }
 
-    // Add Error objects to includeContext and optionally to the message
     if (errorObjects.length > 0) {
       if (errorObjects.length === 1) {
-        // Single error - use 'error' key and append error message to final message
         includeContext.error = errorObjects[0]
         finalMessage = `${finalMessage}: ${errorObjects[0].message}`
       } else {
-        // Multiple errors - use indexed keys and append all error messages
         for (let index = 0; index < errorObjects.length; index++) {
           const error = errorObjects[index]
           includeContext[`error_${index + 1}`] = error
@@ -173,7 +149,6 @@ export function createLogger(filePath: string) {
         finalMessage = `${finalMessage}: ${errorMessages}`
       }
     }
-    // Compare the requested level's priority to current environment's level
     const currentLogLevel = getLogLevelNumber()
     if (LOG_LEVELS[level] > currentLogLevel) {
       return // Do not log if the requested level is lower priority
@@ -183,7 +158,6 @@ export function createLogger(filePath: string) {
     const timestamp = new Date().toISOString()
 
     if (useProductionLogging()) {
-      // Logfmt logging in production
       const logObject: IncludeContext = {
         ...POD_IDENTITY, // pod_name, pod_namespace, node_hostname (static; {} in local dev)
         ...loggerContext, // requestUuid, path, method, headers, etc. (per-request)
@@ -194,7 +168,6 @@ export function createLogger(filePath: string) {
         message: finalMessage,
       }
 
-      // Add any included context to the log object
       const includedContextWithFormattedError = {} as IncludeContext
       for (const [key, value] of Object.entries(includeContext)) {
         if (typeof value === 'object' && value instanceof Error) {
@@ -208,12 +181,11 @@ export function createLogger(filePath: string) {
         }
       }
 
-      // Add extra context to its own key in the log object to prevent conflicts with loggerContext keys
+      // Nested under its own key to avoid colliding with loggerContext keys.
       logObject.included = includedContextWithFormattedError
 
       console.log(toLogfmt(logObject))
     } else {
-      // Human-readable dev/script logging
       const relFile = resolveFilePath(filePath)
       const ts = formatTimestamp()
       const colorFn = LEVEL_COLORS[level]
@@ -221,7 +193,7 @@ export function createLogger(filePath: string) {
       const fileTag = chalk.dim(`(${relFile})`)
       const contextStr = formatContext(includeContext)
 
-      // If the log includes an error, print the Error object to console.error in local dev
+      // Prints the message line once per error, so a two-error call repeats it.
       let wasErrorLog = false
       for (const [, value] of Object.entries(includeContext)) {
         if (typeof value === 'object' && value instanceof Error) {
diff --git a/src/observability/logger/lib/log-levels.ts b/src/observability/logger/lib/log-levels.ts
index 74aad544841c..fcf3fd40a419 100644
--- a/src/observability/logger/lib/log-levels.ts
+++ b/src/observability/logger/lib/log-levels.ts
@@ -1,9 +1,7 @@
 /*
-The log level is controlled by the `LOG_LEVEL` environment variable, where lower log levels = more verbose
- examples:
-   if log level is 'info', only 'info', 'warn', and 'error' logs will be output
-   if log level is 'debug', all logs will be output
-   if log level is 'error', only 'error' logs will be output
+The log level is controlled by the `LOG_LEVEL` environment variable, where lower
+log levels = more verbose. If log level is 'info', only 'info', 'warn', and
+'error' logs are output.
 */
 export const LOG_LEVELS = {
   error: 0,
@@ -19,11 +17,10 @@ function isValidLogLevel(level: string): level is LogLevel {
   return level in LOG_LEVELS
 }
 
-// We set the log level based on the LOG_LEVEL environment variable
-// but default to:
+// Defaults when LOG_LEVEL isn't set:
 //   - 'info' in development
 //   - 'debug' in production
-//   - 'debug' in test - this is because `vitest` turns off logs unless --silent=false is passed
+//   - 'debug' in test, because `vitest` turns off logs unless --silent=false is passed
 export function getLogLevelNumber(): LogLevelValue {
   let defaultLogLevel: LogLevel = 'info'
   if (
diff --git a/src/observability/logger/lib/logger-context.ts b/src/observability/logger/lib/logger-context.ts
index ca129a64933d..baff1072e685 100644
--- a/src/observability/logger/lib/logger-context.ts
+++ b/src/observability/logger/lib/logger-context.ts
@@ -1,10 +1,9 @@
 import { AsyncLocalStorage } from 'async_hooks'
 import type { NextFunction, Request, Response } from 'express'
 
-// Think of this like a Redux store, but for the backend
-// During an early middleware, we call asyncLocalStorage.run(store, () => { next() })
-// This ensures that all downstream middleware can access `store` from the asyncLocalStorage,
-// using the `getLoggerContext` function.
+// Think of this like a Redux store, but for the backend.
+// An early middleware calls asyncLocalStorage.run(store, ...),
+// which lets all downstream middleware read the store via `getLoggerContext`.
 export const asyncLocalStorage = new AsyncLocalStorage()
 
 export type LoggerContext = {
@@ -35,7 +34,6 @@ export function getLoggerContext(): LoggerContext {
   return store as LoggerContext
 }
 
-// Called in subsequent middleware to update the request context
 export function updateLoggerContext(newContext: Partial<LoggerContext>): void {
   const store = asyncLocalStorage.getStore()
   if (!store) {
@@ -65,7 +63,6 @@ export function initLoggerContext(req: Request, res: Response, next: NextFunctio
   const requestUuid = crypto.randomUUID()
 
   const headers = {} as Record<string, string>
-  // Only include the headers we care about
   for (const [key, value] of Object.entries(req.headers)) {
     if (INCLUDE_HEADERS.includes(key)) {
       if (!value) {
@@ -78,7 +75,6 @@ export function initLoggerContext(req: Request, res: Response, next: NextFunctio
     }
   }
 
-  // This is all of the context we want to include for each logger.<method> call
   const store: LoggerContext = {
     requestUuid,
     path: req.path,
@@ -88,7 +84,6 @@ export function initLoggerContext(req: Request, res: Response, next: NextFunctio
     body: req.body,
   }
 
-  // Subsequent middleware and route handlers will have access to the { requestId } store
   asyncLocalStorage.run(store, () => {
     next()
   })
diff --git a/src/observability/logger/lib/pod-identity.ts b/src/observability/logger/lib/pod-identity.ts
index 9ece83385e4d..655b9d967597 100644
--- a/src/observability/logger/lib/pod-identity.ts
+++ b/src/observability/logger/lib/pod-identity.ts
@@ -1,5 +1,5 @@
-// Static pod-identity fields — read once at module load, never change.
-// Only populated when running in Kubernetes (env vars set via Downward API + kube-cluster-metadata).
+// Read once at module load, so these never change.
+// Only populated in Kubernetes (env vars set via Downward API + kube-cluster-metadata).
 export const POD_IDENTITY: Record<string, string> = {}
 if (process.env.POD_NAME) POD_IDENTITY.podName = process.env.POD_NAME
 if (process.env.POD_NAMESPACE) POD_IDENTITY.podNamespace = process.env.POD_NAMESPACE
diff --git a/src/observability/logger/lib/to-logfmt.ts b/src/observability/logger/lib/to-logfmt.ts
index f8c0afbb5964..c1b5f1648243 100644
--- a/src/observability/logger/lib/to-logfmt.ts
+++ b/src/observability/logger/lib/to-logfmt.ts
@@ -14,10 +14,7 @@
  a=1 b.c=2
 */
 
-/**
- * Custom logfmt stringify implementation
- * Based on the original node-logfmt library behavior
- */
+// Matches the original node-logfmt library's quoting and escaping behavior.
 function stringify(data: Record<string, unknown>): string {
   let line = ''
 
@@ -54,7 +51,6 @@ function stringify(data: Record<string, unknown>): string {
 }
 
 export function toLogfmt(jsonString: Record<string, unknown>): string {
-  // Helper function to flatten nested objects
   const flattenObject = (
     obj: Record<string, unknown>,
     parentKey: string = '',
@@ -66,25 +62,21 @@ export function toLogfmt(jsonString: Record<string, unknown>): string {
       const value = obj[key]
 
       if (value && typeof value === 'object') {
-        // Handle circular references
         if (seen.has(value)) {
           result[newKey] = '[Circular]'
           continue
         }
 
-        // Handle Date objects specially
         if (value instanceof Date) {
           result[newKey] = value.toISOString()
           continue
         }
 
-        // Handle arrays
         if (Array.isArray(value)) {
           result[newKey] = value.join(',')
           continue
         }
 
-        // Handle other objects - only flatten if not empty
         const valueKeys = Object.keys(value as Record<string, unknown>)
         if (valueKeys.length > 0) {
           seen.add(value)
@@ -92,7 +84,7 @@ export function toLogfmt(jsonString: Record<string, unknown>): string {
           seen.delete(value)
         }
       } else {
-        // Convert undefined values to null, as they are not supported by logfmt
+        // undefined and empty strings become null, which logfmt can represent.
         result[newKey] =
           value === undefined || (typeof value === 'string' && value === '') ? null : value
       }
diff --git a/src/observability/logger/middleware/get-automatic-request-logger.ts b/src/observability/logger/middleware/get-automatic-request-logger.ts
index 9e55d1c23eea..946695ace75e 100644
--- a/src/observability/logger/middleware/get-automatic-request-logger.ts
+++ b/src/observability/logger/middleware/get-automatic-request-logger.ts
@@ -5,11 +5,7 @@ import { getLogLevelNumber, useProductionLogging } from '@/observability/logger/
 import { toLogfmt } from '@/observability/logger/lib/to-logfmt'
 import { POD_IDENTITY } from '@/observability/logger/lib/pod-identity'
 
-/**
- * Check if automatic development logging is enabled.
- * We don't turn on automatic logging for tests & GitHub Actions by default,
- * but you can override this using the ENABLE_DEV_LOGGING environment variable.
- */
+// Off by default for tests and GitHub Actions. Override with ENABLE_DEV_LOGGING.
 function shouldEnableAutomaticDevLogging(): boolean {
   const isTest = process.env.NODE_ENV === 'test' || process.env.GITHUB_ACTIONS === 'true'
   return Boolean(
@@ -17,23 +13,14 @@ function shouldEnableAutomaticDevLogging(): boolean {
   )
 }
 
-/**
- * Returns a custom middleware that automatically logs request details.
- *
- * e.g. `GET /path/to/resource 200 5.000 ms - 1234`
- *
- * In production, we include the logger context and print in logfmt format
- * In development, we print colored strings for better readability
- * In test, the request details are not logged.
- */
+// Emits one line per response, like: GET /path/to/resource 200 5.000 ms - 1234
+// Tests and Actions stay silent unless ENABLE_DEV_LOGGING overrides.
 export function getAutomaticRequestLogger() {
   return (req: Request, res: Response, next: NextFunction) => {
     const startTime = Date.now()
 
-    // Store original end method to capture response completion
     const originalEnd = res.end
 
-    // Override res.end to log when response completes
     res.end = function (...args: unknown[]) {
       const responseTime = Date.now() - startTime
       const status = res.statusCode || 200
@@ -42,7 +29,6 @@ export function getAutomaticRequestLogger() {
       const url = req.originalUrl || req.url
 
       if (useProductionLogging()) {
-        // Production: log in logfmt format with full context
         const loggerContext = getLoggerContext()
         console.log(
           toLogfmt({
@@ -56,7 +42,6 @@ export function getAutomaticRequestLogger() {
           }),
         )
       } else if (shouldEnableAutomaticDevLogging()) {
-        // Development: log colored strings for readability
         const logLevelNum = getLogLevelNumber()
 
         // Don't log `/_next/` requests unless LOG_LEVEL is `debug` or higher
@@ -64,7 +49,6 @@ export function getAutomaticRequestLogger() {
           return originalEnd.apply(this, args as Parameters<typeof originalEnd>)
         }
 
-        // Choose color based on status code
         const color =
           status >= 500 ? 'red' : status >= 400 ? 'yellow' : status >= 300 ? 'cyan' : 'green'
 
@@ -81,7 +65,6 @@ export function getAutomaticRequestLogger() {
         console.log(logLine)
       }
 
-      // Call the original end method to complete the response
       return originalEnd.apply(this, args as Parameters<typeof originalEnd>)
     }
 
diff --git a/src/observability/middleware/catch-middleware-error.ts b/src/observability/middleware/catch-middleware-error.ts
index d4f754aa7808..99b1870f5747 100644
--- a/src/observability/middleware/catch-middleware-error.ts
+++ b/src/observability/middleware/catch-middleware-error.ts
@@ -1,6 +1,5 @@
 import type { NextFunction, Request, Response, RequestHandler } from 'express'
 
-// Middleware function type that accepts various Express handler signatures.
 // Generic over request/response types so callers with narrower types stay type-safe.
 export interface MiddlewareFn<Req extends Request = Request, Res extends Response = Response> {
   (req: Req, res: Res, next: NextFunction): unknown
diff --git a/src/observability/middleware/handle-errors.ts b/src/observability/middleware/handle-errors.ts
index 0e61539d5c39..f43857cffdf1 100644
--- a/src/observability/middleware/handle-errors.ts
+++ b/src/observability/middleware/handle-errors.ts
@@ -32,7 +32,6 @@ function shouldLogException(error: ErrorWithCode) {
     return false
   }
 
-  // We should log this exception
   return true
 }
 
@@ -55,17 +54,14 @@ async function handleError(
 
   if (req.path.startsWith('/assets') || req.path.startsWith('/_next/static')) {
     if (!responseDone) {
-      // By default, Fastly will cache 404 responses unless otherwise
-      // told not to.
-      // See https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
-      // Let's cache our 404'ing assets conservatively.
-      // The Cache-Control is short, and let's use the default surrogate
-      // key just in case it was a mistake.
+      // Fastly caches 404s by default, so cache 404'ing assets conservatively:
+      // a short Cache-Control, plus the default surrogate key
+      // in case the 404 was a mistake.
+      // https://docs.fastly.com/en/guides/how-caching-and-cdns-work#http-status-codes-cached-by-default
       errorCacheControl(res)
-      // Makes sure the surrogate key is NOT the manual one if it failed.
-      // This basically unsets what was assumed in the beginning of
-      // loading all the middlewares. Falls back to `no-language` when
-      // `req.language` isn't set yet (e.g. errors before language detection).
+      // Unsets the manual surrogate key assumed earlier in the middleware chain.
+      // Falls back to `no-language` when `req.language` isn't set yet,
+      // e.g. errors before language detection.
       setFastlySurrogateKey(res, makeLanguageSurrogateKey(req.language), true)
     }
   } else if (DEBUG_MIDDLEWARE_TESTS) {
@@ -73,9 +69,7 @@ async function handleError(
   }
 
   try {
-    // If the headers have already been sent or the request was aborted...
     if (responseDone) {
-      // Report to Failbot
       if (typeof error !== 'number') {
         await logException(error, req)
       }
@@ -105,21 +99,17 @@ async function handleError(
       req.context.error = error
     }
 
-    // If the error contains a status code, just send that back. This is usually
-    // from a middleware like `express.json()`.
+    // Errors with a status code usually come from a middleware like `express.json()`.
     if (error.statusCode) {
       res.sendStatus(error.statusCode)
       return
     }
 
     res.statusCode = 500
-    // When in local development mode, we don't need the pretty HTML
-    // renderig of 500.tsx.
-    // Incidentally, as Jan 2024, if you try to execute nextApp.renderError
-    // when `NODE_ENV` is 'development' it will hang forever. A problem
-    // we can't fully explain but it's also moot because in local dev
-    // it's easier to just see the full stack trace in the console
-    // and in the client.
+    // Local dev doesn't need the pretty HTML rendering of 500.tsx.
+    // Also, as of Jan 2024, calling nextApp.renderError hangs forever
+    // when `NODE_ENV` is 'development'. We can't fully explain it,
+    // and it's moot because in local dev the full stack trace is more useful.
     if (process.env.NODE_ENV === 'development') {
       next(error)
       return

From 20e9ba9e7b785e74f72582923df57c16c06340a4 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:32:57 +0000
Subject: [PATCH 14/16] Trim excessive comments in src/article-api tests
 (#63280)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/article-api/tests/article-body.ts         |  3 --
 .../tests/audit-logs-transformer.ts           | 11 +------
 .../tests/bespoke-landing-transformer.ts      |  3 --
 .../tests/codeql-cli-transformer.ts           |  4 ---
 .../tests/discovery-landing-transformer.ts    |  7 -----
 src/article-api/tests/get-link-data.ts        |  2 --
 .../tests/github-apps-transformer.ts          | 23 +-------------
 src/article-api/tests/graphql-transformer.ts  | 29 ++---------------
 .../tests/journey-landing-transformer.ts      |  1 -
 src/article-api/tests/pageinfo.ts             |  2 --
 src/article-api/tests/pagelist.ts             | 11 +------
 src/article-api/tests/resolve-path.ts         |  2 --
 src/article-api/tests/rest-transformer.ts     | 31 +------------------
 .../tests/secret-scanning-transformer.ts      |  6 +---
 src/article-api/tests/toc-transformer.ts      |  7 +----
 src/article-api/tests/webhooks-transformer.ts | 13 --------
 16 files changed, 8 insertions(+), 147 deletions(-)

diff --git a/src/article-api/tests/article-body.ts b/src/article-api/tests/article-body.ts
index 932d3e230ebb..ea47acacb8b2 100644
--- a/src/article-api/tests/article-body.ts
+++ b/src/article-api/tests/article-body.ts
@@ -38,7 +38,6 @@ describe('article body api', () => {
     const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
     expect(res.statusCode).toBe(200)
 
-    // Check that octicons without aria-label get auto-generated ones
     expect(res.body).toContain('aria-label="check icon"')
     expect(res.body).toContain('aria-label="git branch icon"')
   })
@@ -47,7 +46,6 @@ describe('article body api', () => {
     const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
     expect(res.statusCode).toBe(200)
 
-    // Check that custom aria-labels are preserved
     expect(res.body).toContain('aria-label="Supported"')
     expect(res.body).toContain('aria-label="Not supported"')
   })
@@ -56,7 +54,6 @@ describe('article body api', () => {
     const res = await get(makeURL('/en/get-started/start-your-journey/hello-world'))
     expect(res.statusCode).toBe(200)
 
-    // Check that octicons with width attribute still get aria-labels
     expect(res.body).toContain('aria-label="rocket icon"')
     expect(res.body).toContain('width="32"')
   })
diff --git a/src/article-api/tests/audit-logs-transformer.ts b/src/article-api/tests/audit-logs-transformer.ts
index d7869a6538ac..9e20c1cd2874 100644
--- a/src/article-api/tests/audit-logs-transformer.ts
+++ b/src/article-api/tests/audit-logs-transformer.ts
@@ -23,21 +23,16 @@ describe('Audit Logs transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for the main heading
     expect(res.body).toContain('# Security log events')
 
-    // Check for intro
     expect(res.body).toContain(
       'Learn about security log events recorded for your personal account.',
     )
 
-    // Check for manual content section heading
     expect(res.body).toContain('## About security log events')
 
-    // Check for new main heading
     expect(res.body).toContain('## Audit log events')
 
-    // Check for category heading
     // The template renders "### Category"
     expect(res.body).toMatch(/### \w+/)
   })
@@ -72,17 +67,14 @@ describe('Audit Logs transformer', () => {
     )
     expect(res.statusCode).toBe(200)
 
-    // Check for event action header
     // #### `action.name`
     expect(res.body).toMatch(/#### `[\w.]+`/)
 
-    // Check for fields section - either common fields summary or additional fields per event
     const body = res.body
     const hasCommonFields = body.includes('### Common fields')
     const hasAdditionalFields = body.includes('**Additional fields:**')
     expect(hasCommonFields || hasAdditionalFields).toBe(true)
 
-    // Validate that a known common field is in the common section and not duplicated
     if (hasCommonFields) {
       const commonFieldsIndex = body.indexOf('### Common fields')
       const commonFieldsSection = body.slice(
@@ -92,7 +84,7 @@ describe('Audit Logs transformer', () => {
       expect(commonFieldsSection).toContain('`action`')
     }
 
-    // Ensure common fields do not appear in any "Additional fields" section
+    // Common fields are listed once in their own section, never repeated per event.
     if (hasAdditionalFields) {
       const additionalSections = body.split('**Additional fields:**').slice(1)
       for (const section of additionalSections) {
@@ -101,7 +93,6 @@ describe('Audit Logs transformer', () => {
       }
     }
 
-    // Check for reference section
     expect(res.body).toContain('**Reference:**')
   })
 
diff --git a/src/article-api/tests/bespoke-landing-transformer.ts b/src/article-api/tests/bespoke-landing-transformer.ts
index 0e6828ea5c0a..3e300116fedc 100644
--- a/src/article-api/tests/bespoke-landing-transformer.ts
+++ b/src/article-api/tests/bespoke-landing-transformer.ts
@@ -12,10 +12,8 @@ describe('bespoke landing transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for title
     expect(res.body).toContain('# Article Grid Bespoke Landing')
 
-    // Should have intro
     expect(res.body).toContain('A test page for testing')
   })
 
@@ -23,7 +21,6 @@ describe('bespoke landing transformer', () => {
     const res = await get(makeURL('/en/get-started/article-grid-bespoke'))
     expect(res.statusCode).toBe(200)
 
-    // Should have Articles section with all descendant articles (recursive)
     expect(res.body).toContain('## Articles')
     expect(res.body).toContain('[Grid Article One]')
     expect(res.body).toContain('[Grid Article Two]')
diff --git a/src/article-api/tests/codeql-cli-transformer.ts b/src/article-api/tests/codeql-cli-transformer.ts
index 2f82ae5279c1..dca2b457f07f 100644
--- a/src/article-api/tests/codeql-cli-transformer.ts
+++ b/src/article-api/tests/codeql-cli-transformer.ts
@@ -21,20 +21,16 @@ describe('codeql cli article body api', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for title injection
     expect(res.body).toContain('# database analyze')
 
-    // Check for intro injection
     expect(res.body).toContain(
       'Analyze a database, producing meaningful results in the context of the source code.',
     )
 
-    // Check for content
     expect(res.body).toContain('## Synopsis')
     expect(res.body).toContain('## Description')
     expect(res.body).toContain('## Options')
 
-    // Verify HTML comments are stripped
     expect(res.body).not.toContain('<!-- markdownlint-disable GHD053 -->')
     expect(res.body).not.toContain('<!-- markdownlint-disable GHD030 -->')
     expect(res.body).not.toContain('<!-- Content after this section is automatically generated -->')
diff --git a/src/article-api/tests/discovery-landing-transformer.ts b/src/article-api/tests/discovery-landing-transformer.ts
index fe013bf7f5e6..8c300d0fd713 100644
--- a/src/article-api/tests/discovery-landing-transformer.ts
+++ b/src/article-api/tests/discovery-landing-transformer.ts
@@ -12,11 +12,9 @@ describe('discovery landing transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for title and intro
     expect(res.body).toContain('# Landing Page Carousel')
     expect(res.body).toContain('A test category page for testing the LandingCarousel component')
 
-    // Should have Articles section with all descendant articles
     expect(res.body).toContain('## Articles')
     expect(res.body).toContain('[Carousel Article One]')
     expect(res.body).toContain('[Carousel Article Two]')
@@ -29,10 +27,8 @@ describe('discovery landing transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for title
     expect(res.body).toContain('# Article Grid Discovery')
 
-    // Should have Articles section with all descendant articles (recursive)
     expect(res.body).toContain('## Articles')
     expect(res.body).toContain('[Grid Article One]')
     expect(res.body).toContain('[Grid Article Two]')
@@ -41,14 +37,11 @@ describe('discovery landing transformer', () => {
   })
 
   test('handles discovery landing structure consistently', async () => {
-    // Discovery pages should have a consistent structure
     const res = await get(makeURL('/en/get-started/carousel'))
     expect(res.statusCode).toBe(200)
 
-    // Should have intro
     expect(res.body).toMatch(/^# .+\n\n.+\n\n/)
 
-    // Should have at least one section
     expect(res.body).toContain('##')
   })
 
diff --git a/src/article-api/tests/get-link-data.ts b/src/article-api/tests/get-link-data.ts
index fc11254faba3..41f9a16b4e39 100644
--- a/src/article-api/tests/get-link-data.ts
+++ b/src/article-api/tests/get-link-data.ts
@@ -2,7 +2,6 @@ import { describe, expect, test, vi } from 'vitest'
 import { getLinkData } from '@/article-api/lib/get-link-data'
 import type { Context, Page, Permalink } from '@/types'
 
-// Helper to create a minimal mock page
 function createMockPage(options: {
   title?: string
   intro?: string
@@ -18,7 +17,6 @@ function createMockPage(options: {
   return page as unknown as Page
 }
 
-// Helper to create a minimal context
 function createContext(currentVersion = 'free-pro-team@latest'): Context {
   return { currentVersion } as unknown as Context
 }
diff --git a/src/article-api/tests/github-apps-transformer.ts b/src/article-api/tests/github-apps-transformer.ts
index 80fc1acfc4bc..d2ff01d2dfcb 100644
--- a/src/article-api/tests/github-apps-transformer.ts
+++ b/src/article-api/tests/github-apps-transformer.ts
@@ -29,13 +29,10 @@ describe('GitHub Apps transformer', () => {
       expect(res.statusCode).toBe(200)
       expect(res.headers['content-type']).toContain('text/markdown')
 
-      // Check for the main heading
       expect(res.body).toContain('# Endpoints available for GitHub App installation access tokens')
 
-      // Should have category headings as h2
       expect(res.body).toMatch(/^## /m)
 
-      // Should not contain HTML comments
       expect(res.body).not.toMatch(/<!--.*?-->/)
     })
 
@@ -46,10 +43,8 @@ describe('GitHub Apps transformer', () => {
       expect(res.statusCode).toBe(200)
       expect(res.headers['content-type']).toContain('text/markdown')
 
-      // Check for the main heading
       expect(res.body).toContain('# Endpoints available for GitHub App user access tokens')
 
-      // Should have category headings as h2
       expect(res.body).toMatch(/^## /m)
     })
 
@@ -62,10 +57,8 @@ describe('GitHub Apps transformer', () => {
       expect(res.statusCode).toBe(200)
       expect(res.headers['content-type']).toContain('text/markdown')
 
-      // Check for the main heading
       expect(res.body).toContain('# Endpoints available for fine-grained personal access tokens')
 
-      // Should have category headings as h2
       expect(res.body).toMatch(/^## /m)
     })
 
@@ -81,7 +74,7 @@ describe('GitHub Apps transformer', () => {
         console.log(`[DEBUG] Test response: ${res.statusCode} in ${Date.now() - startTime}ms`)
       expect(res.statusCode).toBe(200)
 
-      // Check for bullet list items with asterisks (per content guidelines)
+      // Content guidelines require asterisk bullets, not hyphens.
       expect(res.body).toContain('*')
       expect(res.body).toMatch(/\* \[`[A-Z]+ \//)
     })
@@ -94,7 +87,6 @@ describe('GitHub Apps transformer', () => {
       )
       expect(res.statusCode).toBe(200)
 
-      // Check for common HTTP verbs
       expect(res.body).toMatch(/`GET \//)
       // May also have POST, PUT, PATCH, DELETE depending on data
     })
@@ -118,10 +110,8 @@ describe('GitHub Apps transformer', () => {
       expect(res.statusCode).toBe(200)
       expect(res.headers['content-type']).toContain('text/markdown')
 
-      // Check for the main heading
       expect(res.body).toContain('# Permissions required for GitHub Apps')
 
-      // Should have permission group headings as h2
       expect(res.body).toMatch(/^## /m)
     })
 
@@ -134,10 +124,8 @@ describe('GitHub Apps transformer', () => {
       expect(res.statusCode).toBe(200)
       expect(res.headers['content-type']).toContain('text/markdown')
 
-      // Check for the main heading
       expect(res.body).toContain('# Permissions required for fine-grained personal access tokens')
 
-      // Should have permission group headings as h2
       expect(res.body).toMatch(/^## /m)
     })
 
@@ -145,7 +133,6 @@ describe('GitHub Apps transformer', () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
 
-      // Check for table structure
       expect(res.body).toContain('| Endpoint | Access | Tokens | Additional Permissions |')
       expect(res.body).toContain('|----------|--------|--------|------------------------|')
     })
@@ -154,7 +141,6 @@ describe('GitHub Apps transformer', () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
 
-      // Check for access levels in table cells
       expect(res.body).toMatch(/\| read \|/)
       expect(res.body).toMatch(/\| write \|/)
       // May also have admin depending on data
@@ -164,11 +150,9 @@ describe('GitHub Apps transformer', () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
 
-      // Check for legend
       expect(res.body).toContain('UAT = user access token')
       expect(res.body).toContain('IAT = installation access token')
 
-      // Check that token types appear in actual table rows (not just the legend)
       expect(res.body).toMatch(/\|\s*(?:UAT|IAT|UAT, IAT|None)\s*\|/)
     })
 
@@ -176,7 +160,6 @@ describe('GitHub Apps transformer', () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
 
-      // Check for checkmark (✓) or cross (✗) symbols in Additional Permissions column
       expect(res.body).toMatch(/\| [✓✗] \|/)
     })
 
@@ -184,7 +167,6 @@ describe('GitHub Apps transformer', () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
 
-      // Should have multiple permission group headings
       const headings = res.body.match(/^## .* permissions for .*/gm)
       expect(headings).toBeTruthy()
       if (headings) {
@@ -198,7 +180,6 @@ describe('GitHub Apps transformer', () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
 
-      // Check for manual content that should be in the markdown
       expect(res.body).toContain('GitHub Apps are created with a set of permissions')
     })
 
@@ -222,7 +203,6 @@ describe('GitHub Apps transformer', () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
 
-      // Check that AUTOTITLE has been resolved
       expect(res.body).not.toContain('[AUTOTITLE]')
     })
 
@@ -247,7 +227,6 @@ describe('GitHub Apps transformer', () => {
     test('Missing apiVersion defaults to latest', async () => {
       const res = await get(makeURL('/en/rest/authentication/permissions-required-for-github-apps'))
       expect(res.statusCode).toBe(200)
-      // Should work without explicit apiVersion
     })
 
     test('Non-GitHub Apps pages are not transformed', async () => {
diff --git a/src/article-api/tests/graphql-transformer.ts b/src/article-api/tests/graphql-transformer.ts
index f0668c40b88c..127584b86d46 100644
--- a/src/article-api/tests/graphql-transformer.ts
+++ b/src/article-api/tests/graphql-transformer.ts
@@ -8,7 +8,7 @@ const makeURL = (pathname: string): string => {
 }
 
 describe('GraphQL transformer', { timeout: 10000 }, () => {
-  // Cache expensive responses to avoid duplicate requests
+  // Several tests hit the same URL, so cache slow responses to avoid repeated requests.
   const responseCache = new Map<string, Awaited<ReturnType<typeof get>>>()
 
   const getCached = async (url: string) => {
@@ -32,7 +32,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       expect(res.statusCode).toBe(200)
       expect(res.headers['content-type']).toContain('text/markdown')
 
-      // Check for the main heading
       expect(res.body).toContain('# Repositories')
 
       // Items render as flat alphabetical level 2 headings with a kind suffix
@@ -47,10 +46,8 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Item headings are now at level 3
       expect(res.body).toContain('## repository - query')
 
-      // Check for query description
       expect(res.body).toContain('Lookup a given repository by the owner and repository name.')
 
-      // Check for type (without link)
       expect(res.body).toContain('**Type:** Repository')
     })
 
@@ -61,7 +58,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // codeOfConduct query is in the meta category
       expect(res.body).toContain('### Arguments for `codeOfConduct`')
 
-      // Check for specific arguments in bullet format
       expect(res.body).toContain('`key` (String!)')
       expect(res.body).toContain("The code of conduct's key.")
     })
@@ -101,7 +97,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       expect(res.body).toContain('## User - object')
       expect(res.body).toContain('`repositories`')
 
-      // Check for nested argument bullets
       expect(res.body).toContain('`first`')
       expect(res.body).toContain('Returns the first n elements from the list.')
       expect(res.body).toContain('`orderBy`')
@@ -172,10 +167,8 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       const res = await getCached('/en/graphql/reference')
       expect(res.statusCode).toBe(200)
 
-      // Check for main heading
       expect(res.body).toContain('# Reference')
 
-      // Check for intro with liquid variable rendered
       expect(res.body).toMatch(/(GitHub|HubGit) GraphQL API schema/)
     })
   })
@@ -185,15 +178,12 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       const res = await getCached('/en/graphql/overview/changelog')
       expect(res.statusCode).toBe(200)
 
-      // Check for main heading
       expect(res.body).toContain('# Changelog')
 
-      // Check for intro
       expect(res.body).toContain(
         'The GraphQL schema changelog is a list of recent and upcoming changes',
       )
 
-      // Check for manual content
       expect(res.body).toContain(
         'Breaking changes include changes that will break existing queries',
       )
@@ -201,13 +191,10 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       // Index page shows latest year (2026) entries only
       expect(res.body).toContain('## Schema changes for 2026-')
 
-      // Check for change items
       expect(res.body).toContain('### The GraphQL schema includes these changes:')
 
-      // Should NOT contain entries from other years
       expect(res.body).not.toContain('## Schema changes for 2025-')
 
-      // Check for year navigation
       expect(res.body).toContain('2026')
       expect(res.body).toContain('2025')
     })
@@ -216,23 +203,19 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       const res = await getCached('/en/graphql/overview/changelog/2025')
       expect(res.statusCode).toBe(200)
 
-      // Check for year-specific heading
       expect(res.body).toContain('# GraphQL changelog for 2025')
 
-      // Check for date-based changelog sections from 2025
       expect(res.body).toContain('## Schema changes for 2025-')
 
-      // Should NOT contain entries from other years
       expect(res.body).not.toContain('## Schema changes for 2026-')
       expect(res.body).not.toContain('## Schema changes for 2024-')
     })
 
     test('changelog removes HTML tags from changes', async () => {
-      // Use a year page that has the specific test data
+      // The 2025 fixture is the one whose change descriptions contain HTML.
       const res = await getCached('/en/graphql/overview/changelog/2025')
       expect(res.statusCode).toBe(200)
 
-      // Check that HTML tags are removed
       expect(res.body).toContain('Field suggestedReviewerActors was added')
       expect(res.body).not.toContain('<code>')
       expect(res.body).not.toContain('</code>')
@@ -244,17 +227,13 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       const res = await getCached('/en/graphql/overview/breaking-changes')
       expect(res.statusCode).toBe(200)
 
-      // Check for main heading
       expect(res.body).toContain('# Breaking changes')
 
-      // Check for intro
       expect(res.body).toContain('Learn about recent and upcoming breaking changes')
 
-      // Check for manual content
       expect(res.body).toContain('## About breaking changes')
       expect(res.body).toContain('Breaking:** Changes that will break existing queries')
 
-      // Check for date-based sections
       expect(res.body).toContain('## Changes scheduled for 2025-04-01')
       expect(res.body).toContain('## Changes scheduled for 2026-04-01')
     })
@@ -263,7 +242,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       const res = await getCached('/en/graphql/overview/breaking-changes')
       expect(res.statusCode).toBe(200)
 
-      // Check for breaking criticality
       expect(res.body).toMatch(/\*\*Breaking\*\*\s+A change will be made to `\w+\.\w+`\./)
       expect(res.body).toMatch(/\*\*Description:\*\*.*will be removed/)
       expect(res.body).toMatch(/\*\*Reason:\*\*/)
@@ -274,7 +252,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       expect(res.statusCode).toBe(200)
       expect(res.body).toContain('scheduled for')
 
-      // Check that HTML tags are removed from descriptions
       expect(res.body).not.toContain('<p>')
       expect(res.body).not.toContain('</p>')
       expect(res.body).not.toContain('<code>')
@@ -291,7 +268,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       const res = await getCached('/en/graphql/reference/repos')
       expect(res.statusCode).toBe(200)
 
-      // Make sure the raw AUTOTITLE tag is not present
       expect(res.body).not.toContain('[AUTOTITLE]')
     })
 
@@ -308,7 +284,6 @@ describe('GraphQL transformer', { timeout: 10000 }, () => {
       const res = await getCached('/en/graphql/overview/breaking-changes')
       expect(res.statusCode).toBe(200)
 
-      // Check that liquid variables in intro are rendered
       expect(res.body).toMatch(/(GitHub|HubGit) GraphQL API/)
       expect(res.body).not.toContain('{% data variables.product.prodname_dotcom %}')
     })
diff --git a/src/article-api/tests/journey-landing-transformer.ts b/src/article-api/tests/journey-landing-transformer.ts
index 09e56d9af8fc..63a4110695ea 100644
--- a/src/article-api/tests/journey-landing-transformer.ts
+++ b/src/article-api/tests/journey-landing-transformer.ts
@@ -12,7 +12,6 @@ describe('journey landing transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for journey tracks (now under Links section with track title as h3)
     expect(res.body).toContain('## Links')
     expect(res.body).toContain('### First Track')
     expect(res.body).toContain('* [Hello World](/en/get-started/start-your-journey/hello-world)')
diff --git a/src/article-api/tests/pageinfo.ts b/src/article-api/tests/pageinfo.ts
index f17804619633..5739bc97c2f6 100644
--- a/src/article-api/tests/pageinfo.ts
+++ b/src/article-api/tests/pageinfo.ts
@@ -47,9 +47,7 @@ describe('pageinfo api', () => {
       'Get started using HubGit to manage Git repositories and collaborate with others.',
     )
     expect(meta.documentType).toBe('category')
-    // Canonical URLs should not have redirectedFrom
     expect(meta.redirectedFrom).toBeUndefined()
-    // Check that it can be cached at the CDN
     expect(res.headers['set-cookie']).toBeUndefined()
     expect(res.headers['cache-control']).toContain('public')
     expect(res.headers['cache-control']).toMatch(/max-age=[1-9]/)
diff --git a/src/article-api/tests/pagelist.ts b/src/article-api/tests/pagelist.ts
index 0cdb55cfcd04..684d64cde4c8 100644
--- a/src/article-api/tests/pagelist.ts
+++ b/src/article-api/tests/pagelist.ts
@@ -23,7 +23,6 @@ describe.each(allVersionKeys)('pagelist api for %s', async (versionKey) => {
     }
   })
 
-  // queries the pagelist API for each version
   const res = await get(`/api/pagelist/en/${versionKey}`)
 
   test('is reachable, returns 200 OK', async () => {
@@ -82,7 +81,6 @@ describe('Versions API', () => {
 
     const data = JSON.parse(res.body)
 
-    // Check top-level keys exist
     expect(data).toHaveProperty('versions')
     expect(data).toHaveProperty('ghesVersions')
     expect(data).toHaveProperty('ghesLatest')
@@ -91,20 +89,16 @@ describe('Versions API', () => {
     expect(data).toHaveProperty('ghesDeprecated')
     expect(data).toHaveProperty('allVersions')
 
-    // Versions array should contain expected values
     expect(Array.isArray(data.versions)).toBe(true)
     expect(data.versions).toContain('free-pro-team@latest')
     expect(data.versions).toContain('enterprise-cloud@latest')
 
-    // GHES versions should be an array of version strings
     expect(Array.isArray(data.ghesVersions)).toBe(true)
     expect(data.ghesVersions.length).toBeGreaterThan(0)
     expect(data.ghesVersions[0]).toMatch(/^\d+\.\d+$/)
 
-    // ghesLatest should be a valid version string
     expect(data.ghesLatest).toMatch(/^\d+\.\d+$/)
 
-    // allVersions should be an object with version details
     expect(typeof data.allVersions).toBe('object')
     expect(data.allVersions['free-pro-team@latest']).toHaveProperty('version')
     expect(data.allVersions['free-pro-team@latest']).toHaveProperty('versionTitle')
@@ -119,17 +113,14 @@ describe('Languages API', () => {
 
     const data = JSON.parse(res.body)
 
-    // Check top-level keys exist
     expect(data).toHaveProperty('languages')
     expect(data).toHaveProperty('allLanguages')
 
-    // Languages array should contain expected values
     expect(Array.isArray(data.languages)).toBe(true)
     expect(data.languages).toContain('en')
     expect(data.languages).toContain('ja')
     expect(data.languages).toContain('es')
 
-    // allLanguages should be an object with language details
     expect(typeof data.allLanguages).toBe('object')
     expect(data.allLanguages.en).toHaveProperty('name')
     expect(data.allLanguages.en).toHaveProperty('code')
@@ -137,7 +128,7 @@ describe('Languages API', () => {
     expect(data.allLanguages.en).toHaveProperty('locale')
     expect(data.allLanguages.en.name).toBe('English')
 
-    // Should not contain redirectPatterns (not JSON serializable)
+    // redirectPatterns is not JSON serializable, so it must not be in the response.
     expect(data.allLanguages.ja).not.toHaveProperty('redirectPatterns')
   })
 })
diff --git a/src/article-api/tests/resolve-path.ts b/src/article-api/tests/resolve-path.ts
index 6156b8c1e689..3fc654f84fd8 100644
--- a/src/article-api/tests/resolve-path.ts
+++ b/src/article-api/tests/resolve-path.ts
@@ -2,7 +2,6 @@ import { describe, expect, test } from 'vitest'
 import { resolvePath } from '@/article-api/lib/resolve-path'
 import type { Context, Page } from '@/types'
 
-// Helper to create a minimal mock page
 function createMockPage(relativePath: string): Page {
   return {
     relativePath,
@@ -10,7 +9,6 @@ function createMockPage(relativePath: string): Page {
   } as unknown as Page
 }
 
-// Helper to create a minimal context with pages
 function createContext(pages: Record<string, Page>): Context {
   return { pages } as unknown as Context
 }
diff --git a/src/article-api/tests/rest-transformer.ts b/src/article-api/tests/rest-transformer.ts
index cee19cf3a62c..4673e9a89e2a 100644
--- a/src/article-api/tests/rest-transformer.ts
+++ b/src/article-api/tests/rest-transformer.ts
@@ -24,13 +24,10 @@ describe('REST transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for the main heading
     expect(res.body).toContain('# GitHub Actions Artifacts')
 
-    // Check for intro (using fixture's prodname_actions which is 'HubGit Actions')
     expect(res.body).toContain('Use the REST API to interact with artifacts in HubGit Actions.')
 
-    // Check for manual content section heading
     expect(res.body).toContain('## About artifacts in HubGit Actions')
   })
 
@@ -38,13 +35,10 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for operation heading
     expect(res.body).toContain('## List artifacts for a repository')
 
-    // Check for HTTP method and endpoint
     expect(res.body).toContain('GET /repos/{owner}/{repo}/actions/artifacts')
 
-    // Check for operation description
     expect(res.body).toContain('Lists all artifacts for a repository.')
   })
 
@@ -52,13 +46,10 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for parameters heading
     expect(res.body).toContain('### Parameters')
 
-    // Check for headers section
     expect(res.body).toContain('#### Headers')
 
-    // Check for accept header
     expect(res.body).toContain('**`accept`** (string)')
     expect(res.body).toContain('Setting to `application/vnd.github+json` is recommended.')
   })
@@ -67,10 +58,8 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for path and query parameters section
     expect(res.body).toContain('#### Path and query parameters')
 
-    // Check for specific parameters
     expect(res.body).toContain('**`owner`** (string) (required)')
     expect(res.body).toContain('The account owner of the repository.')
 
@@ -90,10 +79,8 @@ describe('REST transformer', () => {
       console.log(`[DEBUG] Test response: ${res.statusCode} in ${Date.now() - startTime}ms`)
     expect(res.statusCode).toBe(200)
 
-    // Check for status codes section
     expect(res.body).toContain('### HTTP response status codes')
 
-    // Check for specific status code
     expect(res.body).toContain('**200**')
     expect(res.body).toContain('OK')
   })
@@ -102,14 +89,11 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for code examples section
     expect(res.body).toContain('### Code examples')
 
-    // Check for request/response labels
     expect(res.body).toContain('**Request:**')
     expect(res.body).toContain('**Response schema (Status: 200):**')
 
-    // Check for curl code block
     expect(res.body).toContain('```curl')
     expect(res.body).toContain('curl -L \\')
     expect(res.body).toContain('-X GET \\')
@@ -120,7 +104,6 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check that auth note is at the top using [!NOTE] syntax
     expect(res.body).toContain('[!NOTE]')
     expect(res.body).toContain('Authorization: Bearer <YOUR-TOKEN>')
     expect(res.body).toContain('application/vnd.github+json')
@@ -130,7 +113,6 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for API version in the auth note (any valid date format)
     expect(res.body).toMatch(/X-GitHub-Api-Version: \d{4}-\d{2}-\d{2}/)
   })
 
@@ -138,7 +120,6 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts', '2022-11-28'))
     expect(res.statusCode).toBe(200)
 
-    // Check for the specified API version in auth note
     expect(res.body).toContain('X-GitHub-Api-Version: 2022-11-28')
   })
 
@@ -150,7 +131,6 @@ describe('REST transformer', () => {
     expect(res.body).toContain('HubGit Actions')
     expect(res.body).not.toContain('{% data variables.product.prodname_actions %}')
 
-    // Check in both the intro and the manual content section
     expect(res.body).toMatch(/Use the REST API to interact with artifacts in HubGit Actions/)
     expect(res.body).toMatch(/About artifacts in HubGit Actions/)
   })
@@ -159,15 +139,12 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check that AUTOTITLE has been resolved to actual link text
     // The link should have the actual page title, not "AUTOTITLE"
     expect(res.body).toContain('[Storing workflow data as artifacts]')
     expect(res.body).toContain('(/en/actions/using-workflows/storing-workflow-data-as-artifacts)')
 
-    // Make sure the raw AUTOTITLE tag is not present
     expect(res.body).not.toContain('[AUTOTITLE]')
 
-    // Verify the link appears in the manual content section
     expect(res.body).toMatch(
       /About artifacts in HubGit Actions[\s\S]*Storing workflow data as artifacts/,
     )
@@ -177,7 +154,6 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check that markdown links are preserved
     expect(res.body).toMatch(/\[.*?\]\(\/en\/.*?\)/)
   })
 
@@ -185,14 +161,12 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for markdown-formatted schema
     expect(res.body).toContain('**Response schema (Status: 200):**')
 
     // Schema should be rendered as a markdown bullet list, not JSON
     expect(res.body).toContain('* `total_count`:')
     expect(res.body).toContain('* `artifacts`:')
 
-    // Should not contain raw JSON Schema keywords
     expect(res.body).not.toContain('"properties":')
   })
 
@@ -240,7 +214,6 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
 
     expect(res.statusCode).toBe(200)
-    // Should include the default API version in auth note (any valid date format)
     expect(res.body).toMatch(/X-GitHub-Api-Version: \d{4}-\d{2}-\d{2}/)
   })
 
@@ -248,7 +221,6 @@ describe('REST transformer', () => {
     const res = await get(makeURL('/en/rest/actions/artifacts'))
     expect(res.statusCode).toBe(200)
 
-    // Check for multiple operation headings
     expect(res.body).toContain('## List artifacts for a repository')
     expect(res.body).toContain('## Get an artifact')
     expect(res.body).toContain('## Delete an artifact')
@@ -281,7 +253,7 @@ describe('REST transformer', () => {
     // because it looks for 'rest' in the path and gets the category/subcategory after it
     // e.g. /ja/rest/actions/artifacts should work the same as /en/rest/actions/artifacts
 
-    // Verify the operation content is present (in English, since REST data is not translated)
+    // REST data is not translated, so the operation content is English either way.
     expect(res.body).toContain('## List artifacts for a repository')
     expect(res.body).toContain('GET /repos/{owner}/{repo}/actions/artifacts')
 
@@ -294,7 +266,6 @@ describe('REST transformer', () => {
     // One of them must be present
     expect(hasJapaneseTitle || hasEnglishTitle).toBe(true)
 
-    // Verify the appropriate content based on which language was served
     if (hasJapaneseTitle) {
       // If Japanese is loaded, expect Japanese intro text
       expect(res.body).toContain('アーティファクト')
diff --git a/src/article-api/tests/secret-scanning-transformer.ts b/src/article-api/tests/secret-scanning-transformer.ts
index be236faf377a..c5daac87568e 100644
--- a/src/article-api/tests/secret-scanning-transformer.ts
+++ b/src/article-api/tests/secret-scanning-transformer.ts
@@ -13,20 +13,16 @@ describe('secret scanning article body api', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for expected content
     expect(res.body).toContain('# Supported secret scanning patterns')
     expect(res.body).toContain('## Supported secrets')
 
-    // Verify HTML comments are stripped
     expect(res.body).not.toMatch(/<!--.*?-->/)
 
-    // Verify HTML icon spans are not present (would be replaced with ✓/✗)
+    // The icon spans are replaced with plain ✓/✗ characters.
     expect(res.body).not.toMatch(/<span[^>]*aria-label="Supported"/)
     expect(res.body).not.toMatch(/<span[^>]*aria-label="Unsupported"/)
-    // Verify no raw HTML span tags remain
     expect(res.body).not.toMatch(/<span[^>]*>/)
 
-    // Verify table content is present with providers
     expect(res.body).toMatch(/|\s*Provider\s*|/)
     expect(res.body).toMatch(/\| (Adafruit|AWS|Alibaba|Amazon)/)
 
diff --git a/src/article-api/tests/toc-transformer.ts b/src/article-api/tests/toc-transformer.ts
index 4bef199a0879..6edd660fadd0 100644
--- a/src/article-api/tests/toc-transformer.ts
+++ b/src/article-api/tests/toc-transformer.ts
@@ -12,12 +12,11 @@ describe('toc transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for title and intro
     expect(res.body).toContain('# Category page of GitHub Actions')
     expect(res.body).toContain('Learn how to migrate your existing CI/CD workflows')
 
-    // Should have Links section with children (uses full title, not shortTitle)
     expect(res.body).toContain('## Links')
+    // Child links use the full title, not shortTitle.
     expect(res.body).toContain('[Subcategory page about Actions](/en/actions/category/subcategory)')
   })
 
@@ -27,10 +26,8 @@ describe('toc transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Check for title
     expect(res.body).toContain('# Subcategory page about Actions')
 
-    // Should have Links section with children
     expect(res.body).toContain('## Links')
   })
 
@@ -46,10 +43,8 @@ describe('toc transformer', () => {
     const res = await get(makeURL('/en/actions/category/subcategory'))
     expect(res.statusCode).toBe(200)
 
-    // Should NOT have href paths as titles
     expect(res.body).not.toContain('* [/en/actions/category/subcategory/')
 
-    // Should have proper article titles (or shortTitle)
     expect(res.body).toMatch(/\[.*\]\(\/en\/actions\/category\/subcategory\/.*\)/)
   })
 })
diff --git a/src/article-api/tests/webhooks-transformer.ts b/src/article-api/tests/webhooks-transformer.ts
index 8c611b285177..32f6db087ac0 100644
--- a/src/article-api/tests/webhooks-transformer.ts
+++ b/src/article-api/tests/webhooks-transformer.ts
@@ -22,10 +22,8 @@ describe('Webhooks transformer', () => {
     expect(res.statusCode).toBe(200)
     expect(res.headers['content-type']).toContain('text/markdown')
 
-    // Should have title
     expect(res.body).toContain('# Webhook events and payloads')
 
-    // Should have intro
     expect(res.body).toContain('Learn about when each webhook event occurs')
   })
 
@@ -33,7 +31,6 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Check for webhook event headers (## webhook_name)
     expect(res.body).toMatch(/^## \w+/m)
   })
 
@@ -41,7 +38,6 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Should list action types for webhooks with multiple actions
     expect(res.body).toContain('**Action type:**')
   })
 
@@ -49,7 +45,6 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Should show availability as a heading
     expect(res.body).toContain('### Availability')
   })
 
@@ -57,7 +52,6 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Check for some known manual content from the markdown file
     expect(res.body).toContain('About webhook events and payloads')
   })
 
@@ -73,7 +67,6 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Check that data variables are rendered (not left as Liquid syntax)
     expect(res.body).not.toContain('{% data')
     expect(res.body).not.toContain('{{')
   })
@@ -90,10 +83,8 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Should show payload object parameters section
     expect(res.body).toContain('### Webhook payload object')
     expect(res.body).toContain('#### Webhook payload object parameters')
-    // Should have a markdown table with parameter columns (may have extra spacing from formatting)
     expect(res.body).toMatch(/\|\s*Name\s*\|\s*Type\s*\|\s*Description\s*\|/)
   })
 
@@ -101,7 +92,6 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Should include webhook descriptions (converted from HTML to plain text)
     // Using actual descriptions from real webhook data
     expect(res.body).toContain('A check run was completed')
   })
@@ -110,11 +100,9 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Should show parameter names and types in tables
     expect(res.body).toContain('`action`')
     expect(res.body).toContain('`string`')
     expect(res.body).toContain('`object`')
-    // Should mark required parameters
     expect(res.body).toContain('**Required.**')
   })
 
@@ -132,7 +120,6 @@ describe('Webhooks transformer', () => {
     const res = await get(makeURL('/en/webhooks/webhook-events-and-payloads'))
     expect(res.statusCode).toBe(200)
 
-    // Should have a common parameters section at the top
     expect(res.body).toContain('## Common payload parameters')
     expect(res.body).toContain('Most webhook events include these standard parameters')
 

From e3034ac8902ceff954c76509eb30176c2a46dc62 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 21:44:55 +0000
Subject: [PATCH 15/16] Trim excessive comments in the rest of
 src/content-render (#63278)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/content-render/liquid/data.ts             |  2 --
 src/content-render/liquid/engine.ts           |  3 --
 src/content-render/liquid/ifversion.ts        | 16 ++--------
 .../liquid/indented-data-reference.ts         |  2 --
 src/content-render/liquid/octicon.ts          |  6 ----
 src/content-render/liquid/prompt.ts           |  4 ---
 src/content-render/tests/annotate.ts          |  8 -----
 .../tests/copilot-code-blocks.ts              | 30 -------------------
 .../tests/link-error-line-numbers.ts          |  8 -----
 src/content-render/tests/liquid-tags.ts       |  9 ------
 src/content-render/tests/prompt-id.ts         |  1 -
 src/content-render/tests/prompt.ts            |  4 ---
 src/content-render/types.ts                   | 19 ------------
 src/content-render/unified/annotate.ts        |  9 ------
 .../unified/collect-mini-toc.ts               |  1 -
 src/content-render/unified/copilot-prompt.ts  |  1 -
 src/content-render/unified/module-types.d.ts  |  4 ---
 .../unified/rewrite-local-links.ts            |  6 +---
 .../unified/rewrite-table-captions.ts         | 18 ++---------
 src/content-render/unified/text-only.ts       |  1 -
 .../unified/use-english-headings.ts           |  4 ---
 21 files changed, 7 insertions(+), 149 deletions(-)

diff --git a/src/content-render/liquid/data.ts b/src/content-render/liquid/data.ts
index bafe90d364a0..44c0151cd40b 100644
--- a/src/content-render/liquid/data.ts
+++ b/src/content-render/liquid/data.ts
@@ -91,7 +91,6 @@ function handleIndent(tagToken: TagToken, text: string): string {
 // keep the blockquote character on every successive line.
 const blockquoteRegexp = /^\n?([ \t]*>[ \t]?)/
 function handleBlockquote(tagToken: TagToken, text: string): string {
-  // If the text isn't multiline, skip
   if (text.split('\n').length <= 1) return text
 
   // If the line with the liquid tag starts with a blockquote...
@@ -100,7 +99,6 @@ function handleBlockquote(tagToken: TagToken, text: string): string {
   const inputLine = input.split('\n').find((line) => line.includes(content))
   if (!inputLine || !blockquoteRegexp.test(inputLine)) return text
 
-  // Keep the character on successive lines
   const match = inputLine.match(blockquoteRegexp)
   if (!match) return text
   const start = match[0]
diff --git a/src/content-render/liquid/engine.ts b/src/content-render/liquid/engine.ts
index 2d10036d94f8..11418f9cfd9a 100644
--- a/src/content-render/liquid/engine.ts
+++ b/src/content-render/liquid/engine.ts
@@ -77,9 +77,6 @@ engine.registerFilter('render_liquid', function (this: FilterScope, input: unkno
   return engine.parseAndRender(input, this.context.environments)
 })
 
-/**
- * Convert the input to a slug
- */
 engine.registerFilter('slugify', (input: string): string => {
   const slugger = new GithubSlugger()
   return slugger.slug(input)
diff --git a/src/content-render/liquid/ifversion.ts b/src/content-render/liquid/ifversion.ts
index adc1b16d5ccb..38c724517a18 100644
--- a/src/content-render/liquid/ifversion.ts
+++ b/src/content-render/liquid/ifversion.ts
@@ -95,21 +95,19 @@ export default class Ifversion extends Tag {
     for (const branch of this.branches) {
       let resolvedBranchCond = branch.cond
 
-      // Resolve "not" keywords in the conditional, if any.
       resolvedBranchCond = this.handleNots(resolvedBranchCond)
 
       // Resolve special operators in the conditional, if any.
       // This will replace syntax like `fpt or ghes < 3.0` with `fpt or true` or `fpt or false`.
       resolvedBranchCond = this.handleOperators(resolvedBranchCond)
 
-      // Resolve version names to boolean values for Markdown API context.
-      // This will replace syntax like `fpt or ghec` with `true or false` based on current version.
-      // Only apply this transformation in Markdown API context to avoid breaking existing functionality.
+      // Replace syntax like `fpt or ghec` with `true or false` based on the current
+      // version. Only done for the Markdown API, where the version names would
+      // otherwise be undefined.
       if ((ctx.environments as IfversionEnvironments).markdownRequested) {
         resolvedBranchCond = this.handleVersionNames(resolvedBranchCond)
       }
 
-      // Use Liquid's native function for the final evaluation.
       const cond = yield new Value(resolvedBranchCond, this.liquid).value(ctx, ctx.opts.lenientIf)
 
       if (isTruthy(cond, ctx)) {
@@ -125,7 +123,6 @@ export default class Ifversion extends Tag {
 
     const condArray = resolvedBranchCond.split(' ')
 
-    // Find the first index in the array that contains "not".
     const notIndex = condArray.findIndex((el: string) => el === 'not')
 
     // E.g., ['not', 'fpt']
@@ -156,7 +153,6 @@ export default class Ifversion extends Tag {
     // If this conditional contains multiple parts using `or` or `and`, get only the conditional with operators.
     const condArray = resolvedBranchCond.split(' ')
 
-    // Find the first index in the array that contains an operator.
     const operatorIndex = condArray.findIndex((el: string) =>
       supportedOperators.find((op: string) => el === op),
     )
@@ -164,7 +160,6 @@ export default class Ifversion extends Tag {
     // E.g., ['ghes', '<', '3.1']
     const condParts = condArray.slice(operatorIndex - 1, operatorIndex + 2)
 
-    // Assign to vars.
     const [versionShortName, operator, releaseToEvaluate] = condParts
 
     // Make sure the operator is supported and the release number matches `\d\d?\.\d\d?`
@@ -219,17 +214,12 @@ export default class Ifversion extends Tag {
       return resolvedBranchCond
     }
 
-    // Split the condition into tokens for processing
     const tokens = resolvedBranchCond.split(/\s+/)
     const processedTokens = tokens.map((token: string) => {
-      // Check if the token is a version short name (fpt, ghec, ghes, ghae)
       const versionShortNames = ['fpt', 'ghec', 'ghes', 'ghae']
       if (versionShortNames.includes(token)) {
-        // Transform version names to boolean values for Markdown API
-        // This fixes the original issue where version names were undefined in API context
         return token === this.currentVersionObj!.shortName ? 'true' : 'false'
       }
-      // Return the token unchanged if it's not a version name
       return token
     })
 
diff --git a/src/content-render/liquid/indented-data-reference.ts b/src/content-render/liquid/indented-data-reference.ts
index 63ad23e1c942..b5b7f589d73b 100644
--- a/src/content-render/liquid/indented-data-reference.ts
+++ b/src/content-render/liquid/indented-data-reference.ts
@@ -47,7 +47,6 @@ const IndentedDataReference = {
 
     assert(parseInt(numSpaces) || numSpaces === '0', '"spaces=NUMBER" must include a number')
 
-    // Get the referenced value from the context
     const text: string | undefined = getDataByLanguage(
       dataReference,
       scope.environments.currentLanguage,
@@ -63,7 +62,6 @@ const IndentedDataReference = {
       return
     }
 
-    // add spaces to each line
     const renderedReferenceWithIndent: string = text.replace(/^/gm, ' '.repeat(parseInt(numSpaces)))
 
     return this.liquid.parseAndRender(renderedReferenceWithIndent, scope.environments)
diff --git a/src/content-render/liquid/octicon.ts b/src/content-render/liquid/octicon.ts
index ca5a40fa7379..aacb8927e791 100644
--- a/src/content-render/liquid/octicon.ts
+++ b/src/content-render/liquid/octicon.ts
@@ -25,7 +25,6 @@ const Octicon = {
       throw new TokenizationError(SyntaxHelp, tagToken)
     }
 
-    // Memoize the icon
     this.icon = match.groups.icon
     // Breaking change in octicons 12
     // https://github.com/primer/octicons/releases/tag/v12.0.0
@@ -36,29 +35,24 @@ const Octicon = {
 
     this.options = {}
 
-    // Memoize any options passed
     if (match.groups.options) {
       let optionsMatch: RegExpExecArray | null
 
-      // Loop through each option matching the OptionsSyntax regex
       while ((optionsMatch = OptionsSyntax.exec(match.groups.options))) {
         // Pull out the key/value ([0] is the whole input)
         const [, key, value] = optionsMatch
         this.options[key] = value
 
-        // Alias label to aria-label
         if (key === 'label') this.options['aria-label'] = value
       }
     }
   },
 
   async render(): Promise<string> {
-    // Throw an error if the requested octicon does not exist.
     if (!Object.prototype.hasOwnProperty.call(octicons, this.icon)) {
       throw new Error(`Octicon ${this.icon} does not exist`)
     }
 
-    // Auto-generate aria-label if not provided
     // Replace non-alphanumeric characters with spaces and append " icon"
     if (!this.options['aria-label']) {
       const defaultLabel = `${this.icon.toLowerCase().replace(/[^a-z0-9]+/gi, ' ')} icon`
diff --git a/src/content-render/liquid/prompt.ts b/src/content-render/liquid/prompt.ts
index dbba2b28b3c4..1df9e1bcd28a 100644
--- a/src/content-render/liquid/prompt.ts
+++ b/src/content-render/liquid/prompt.ts
@@ -1,4 +1,3 @@
-// src/content-render/liquid/prompt.ts
 // Defines {% prompt %}…{% endprompt %} to wrap its content in <code> and append the Copilot icon.
 
 import octicons from '@primer/octicons'
@@ -15,7 +14,6 @@ interface LiquidTag {
 export const Prompt: LiquidTag = {
   type: 'block',
 
-  // Collect everything until {% endprompt %}
   parse(tagToken: TagToken, remainTokens: TopLevelToken[]): void {
     this.templates = []
     const stream = this.liquid.parser.parseStream(remainTokens)
@@ -28,12 +26,10 @@ export const Prompt: LiquidTag = {
     stream.start()
   },
 
-  // Render the inner Markdown, wrap in <code>, then append the SVG
   *render(scope: unknown): Generator<unknown, string, unknown> {
     const content = yield this.liquid.renderer.renderTemplates(this.templates, scope)
     const contentString = String(content)
 
-    // build a URL with the prompt text encoded as query parameter
     const promptParam: string = encodeURIComponent(contentString)
     const href: string = `https://github.com/copilot?prompt=${promptParam}`
     // Use murmur hash for deterministic ID (avoids hydration mismatch)
diff --git a/src/content-render/tests/annotate.ts b/src/content-render/tests/annotate.ts
index 20083164d3bf..c47a78d6fb76 100644
--- a/src/content-render/tests/annotate.ts
+++ b/src/content-render/tests/annotate.ts
@@ -22,33 +22,27 @@ describe('annotate', () => {
     const res = await renderContent(example)
     const $ = load(res)
 
-    // Check that the annotation structure is rendered correctly
     const annotation = $('.annotate')
     expect(annotation.length).toBe(1)
     expect(annotation.hasClass('beside')).toBe(true)
 
-    // Check annotation header exists
     const header = $('.annotate-header')
     expect(header.length).toBe(1)
 
-    // Check both beside and inline modes are rendered
     const beside = $('.annotate-beside')
     const inline = $('.annotate-inline')
     expect(beside.length).toBe(1)
     expect(inline.length).toBe(1)
 
-    // Check that we have the correct number of annotation rows
     const rows = $('.annotate-row')
     expect(rows.length).toBe(2)
 
-    // Check that each row has both code and note sections
     rows.each((i, row) => {
       const $row = $(row)
       expect($row.find('.annotate-code').length).toBe(1)
       expect($row.find('.annotate-note').length).toBe(1)
     })
 
-    // Check specific content of the annotations
     const notes = $('.annotate-note p')
     const noteTexts = notes.map((i, el) => $(el).text()).get()
     expect(noteTexts).toEqual([
@@ -56,7 +50,6 @@ describe('annotate', () => {
       'Add the pull_request event, so that the workflow runs automatically\nevery time a pull request is created.',
     ])
 
-    // Check code content
     const codes = $('.annotate-code pre')
     const codeTexts = codes.map((i, el) => $(el).text()).get()
     expect(codeTexts).toEqual([
@@ -157,7 +150,6 @@ on: [push]
     const rows = $('.annotate-row')
     const notes = $('.annotate-note', rows)
 
-    // Check that AUTOTITLE links were resolved to actual titles
     const firstNote = notes.eq(0).html()
     const secondNote = notes.eq(1).html()
 
diff --git a/src/content-render/tests/copilot-code-blocks.ts b/src/content-render/tests/copilot-code-blocks.ts
index 51209f95663e..2dfe76d6b4c2 100644
--- a/src/content-render/tests/copilot-code-blocks.ts
+++ b/src/content-render/tests/copilot-code-blocks.ts
@@ -18,11 +18,8 @@ describe('code-header plugin', () => {
 
       const html = await renderContent(markdown)
 
-      // Should keep copilot as the language (not convert to text without copy meta)
       expect(html).toContain('language-copilot')
-      // Should NOT wrap in code-example div since no copy meta
       expect(html).not.toContain('code-example')
-      // Should NOT have header since no copy meta
       expect(html).not.toContain('<header')
     })
 
@@ -31,13 +28,10 @@ describe('code-header plugin', () => {
 
       const html = await renderContent(markdown)
 
-      // Should be wrapped in code-example div
       expect(html).toContain('code-example')
-      // Should have header with copy button
       expect(html).toContain('<header')
       expect(html).toContain('js-btn-copy')
       expect(html).toContain('language-copilot')
-      // Should NOT have prompt button (no prompt meta)
       expect(html).not.toContain('https://github.com/copilot?prompt=')
     })
 
@@ -46,14 +40,10 @@ describe('code-header plugin', () => {
 
       const html = await renderContent(markdown)
 
-      // Should be wrapped in code-example div
       expect(html).toContain('code-example')
-      // Should have header
       expect(html).toContain('<header')
-      // Should have prompt button
       expect(html).toContain('https://github.com/copilot?prompt=')
       expect(html).toContain('language-copilot')
-      // Should NOT have copy button
       expect(html).not.toContain('js-btn-copy')
     })
 
@@ -62,15 +52,11 @@ describe('code-header plugin', () => {
 
       const html = await renderContent(markdown)
 
-      // Should be wrapped in code-example div
       expect(html).toContain('code-example')
-      // Should have header with copy button
       expect(html).toContain('<header')
       expect(html).toContain('js-btn-copy')
-      // Should have prompt button with encoded URL
       expect(html).toContain('https://github.com/copilot?prompt=')
       expect(html).toContain('Improve%20the%20variable%20names%20in%20this%20function')
-      // Should have Copilot icon button
       expect(html).toContain('aria-label="Run this prompt in Copilot Chat"')
       expect(html).toContain('language-copilot')
     })
@@ -94,12 +80,9 @@ Improve the variable names in this function
 
       const html = await renderContent(markdown)
 
-      // Should have prompt button with both code blocks in URL
       expect(html).toContain('https://github.com/copilot?prompt=')
-      // Should contain encoded content from both the referenced code and the prompt
       expect(html).toContain('function%20logPersonsAge')
       expect(html).toContain('Improve%20the%20variable%20names')
-      // Should have different aria-label indicating context
       expect(html).toContain('aria-label="Run this prompt with context in Copilot Chat"')
     })
 
@@ -122,14 +105,10 @@ Improve the variable names in this function
 
       const html = await renderContent(markdown)
 
-      // Should have prompt button with both code blocks in URL
       expect(html).toContain('https://github.com/copilot?prompt=')
-      // Should contain encoded content from both the referenced code and the prompt
       expect(html).toContain('function%20logPersonsAge')
       expect(html).toContain('Improve%20the%20variable%20names')
-      // Should have different aria-label indicating context
       expect(html).toContain('aria-label="Run this prompt with context in Copilot Chat"')
-      // Should NOT have copy button
       expect(html).not.toContain('js-btn-copy')
     })
   })
@@ -143,19 +122,14 @@ Improve the variable names in this function
 
       const html = await renderContent(markdown)
 
-      // Should warn about missing reference via structured logger
       expect(mockWarn).toHaveBeenCalledWith('Cannot find referenced code block', {
         ref: 'nonexistent-id',
       })
 
-      // Should still render with prompt button using current code only
       expect(html).toContain('https://github.com/copilot?prompt=')
       expect(html).toContain('Improve%20the%20variable%20names%20in%20this%20function')
-      // Should NOT contain any referenced code since none was found
       expect(html).not.toContain('function%20logPersonsAge')
-      // Should have standard aria-label (not context version)
       expect(html).toContain('aria-label="Run this prompt in Copilot Chat"')
-      // Should not crash or fail
       expect(html).toContain('code-example')
 
       mockWarn.mockClear()
@@ -169,7 +143,6 @@ function test() {}
 
       const html = await renderContent(markdown)
 
-      // Should NOT wrap in code-example div (annotated blocks are excluded)
       expect(html).not.toContain('code-example')
     })
 
@@ -178,7 +151,6 @@ function test() {}
 
       const html = await renderContent(markdown)
 
-      // Should render with copy button
       expect(html).toContain('code-example')
       expect(html).toContain('js-btn-copy')
       expect(html).toContain('language-javascript')
@@ -191,7 +163,6 @@ function test() {}
 
       const html = await renderContent(markdown)
 
-      // Should encode quotes and ampersands properly
       expect(html).toContain('%22quotes%22')
       expect(html).toContain('%26%20symbols')
     })
@@ -204,7 +175,6 @@ This is line 2
 
       const html = await renderContent(markdown)
 
-      // Should encode newlines properly
       expect(html).toContain('This%20is%20line%201%0AThis%20is%20line%202')
     })
   })
diff --git a/src/content-render/tests/link-error-line-numbers.ts b/src/content-render/tests/link-error-line-numbers.ts
index 4c1d9255e421..36cd3d1f842e 100644
--- a/src/content-render/tests/link-error-line-numbers.ts
+++ b/src/content-render/tests/link-error-line-numbers.ts
@@ -10,14 +10,12 @@ describe('link error line numbers', () => {
   let mockContext: Context
 
   beforeEach(async () => {
-    // Set up file system mocking
     fs = await import('fs')
     originalReadFileSync = fs.default.readFileSync
     originalExistsSync = fs.default.existsSync
 
     fs.default.existsSync = () => true
 
-    // Set up basic mock context
     mockContext = {
       currentLanguage: 'en',
       currentVersion: 'free-pro-team@latest',
@@ -30,13 +28,11 @@ describe('link error line numbers', () => {
   })
 
   afterEach(() => {
-    // Restore original functions
     fs.default.readFileSync = originalReadFileSync
     fs.default.existsSync = originalExistsSync
   })
 
   test('reports correct line numbers for broken AUTOTITLE links', async () => {
-    // Test content with frontmatter followed by content with a broken link
     const template = `---
 title: Test Page
 version: 1.0
@@ -72,7 +68,6 @@ More content here.`
       fullPath: '/fake/test-file-2.md',
     } as unknown as Context['page']
 
-    // Test with more extensive frontmatter
     const template = `---
 title: Another Test Page
 description: This is a test
@@ -109,7 +104,6 @@ Content with a [AUTOTITLE](/another/nonexistent/page) link.`
       fullPath: '/fake/no-frontmatter.md',
     } as unknown as Context['page']
 
-    // Test content without frontmatter
     const template = `# Simple Title
 
 This is content without frontmatter.
@@ -148,7 +142,6 @@ title: Message Test
     } catch (error) {
       expect(error).toBeInstanceOf(TitleFromAutotitleError)
 
-      // Check that the new error message format is used
       expect((error as TitleFromAutotitleError).message).toContain(
         'could not be resolved in one or more versions',
       )
@@ -157,7 +150,6 @@ title: Message Test
       )
       expect((error as TitleFromAutotitleError).message).toContain('/test/broken/link')
 
-      // Check that the old error message format is NOT used
       expect((error as TitleFromAutotitleError).message).not.toContain('Unable to find Page by')
       expect((error as TitleFromAutotitleError).message).not.toContain('To fix it, look at')
     }
diff --git a/src/content-render/tests/liquid-tags.ts b/src/content-render/tests/liquid-tags.ts
index 0209be92c090..db28d494733b 100644
--- a/src/content-render/tests/liquid-tags.ts
+++ b/src/content-render/tests/liquid-tags.ts
@@ -10,16 +10,13 @@ describe('liquid-tags script integration tests', () => {
   vi.setConfig({ testTimeout: 60 * 1000 })
 
   beforeEach(async () => {
-    // Create test directory
     await fs.mkdir(testContentDir, { recursive: true })
   })
 
   afterEach(async () => {
-    // Clean up test files
     await fs.rm(testContentDir, { recursive: true, force: true })
   })
 
-  // Helper function to run script commands
   async function runScript(args: string): Promise<{ output: string; exitCode: number }> {
     let output = ''
     let exitCode = 0
@@ -41,7 +38,6 @@ describe('liquid-tags script integration tests', () => {
   }
 
   test('expand command should complete successfully with basic content', async () => {
-    // Create a test file with liquid reference
     const testFile = path.join(testContentDir, 'basic-test.md')
     const testContent = `---
 title: Test
@@ -54,11 +50,9 @@ This uses {% data variables.product.prodname_dotcom %} in content.
 
     const { output, exitCode } = await runScript(`expand --paths "${testFile}"`)
 
-    // Should complete without error
     expect(exitCode, `Script failed with output: ${output}`).toBe(0)
     expect(output.length).toBeGreaterThan(0)
 
-    // Check that the file was modified
     const expandedContent = await fs.readFile(testFile, 'utf8')
     expect(expandedContent).not.toBe(testContent)
     expect(expandedContent).toContain('GitHub') // Should expand to actual fixture value
@@ -75,16 +69,13 @@ This uses {% data variables.product.prodname_dotcom %} in content.
 
     await fs.writeFile(testFile, originalContent)
 
-    // First expand
     await runScript(`expand --paths "${testFile}"`)
 
-    // Then restore
     const { output, exitCode } = await runScript(`restore --paths "${testFile}"`)
 
     expect(exitCode, `Restore script failed with output: ${output}`).toBe(0)
     expect(output.length).toBeGreaterThan(0)
 
-    // Should be back to original liquid tags
     const restoredContent = await fs.readFile(testFile, 'utf8')
     expect(restoredContent).toContain('{% data variables.product.prodname_dotcom %}')
     expect(restoredContent).not.toContain('GitHub')
diff --git a/src/content-render/tests/prompt-id.ts b/src/content-render/tests/prompt-id.ts
index ce7441e8832b..71e046b0fd48 100644
--- a/src/content-render/tests/prompt-id.ts
+++ b/src/content-render/tests/prompt-id.ts
@@ -55,7 +55,6 @@ describe('generatePromptId', () => {
     expect(typeof id).toBe('string')
     expect(id.length).toBeGreaterThan(0)
 
-    // Should be different from just the prompt text alone
     expect(id).not.toBe(generatePromptId(promptText))
   })
 
diff --git a/src/content-render/tests/prompt.ts b/src/content-render/tests/prompt.ts
index 65de51fea1c3..e8e250e166e1 100644
--- a/src/content-render/tests/prompt.ts
+++ b/src/content-render/tests/prompt.ts
@@ -6,18 +6,14 @@ describe('prompt tag', () => {
     const input: string = 'Here is your prompt: {% prompt %}example prompt text{% endprompt %}.'
     const output: string = await renderContent(input)
 
-    // Should have code element with ID
     expect(output).toContain('<code id="')
     expect(output).toContain('>example prompt text</code>')
 
-    // Should have two responsive anchor elements
     expect(output).toContain('copilot-prompt-long')
     expect(output).toContain('copilot-prompt-short')
 
-    // Should contain SVG icons
     expect(output).toContain('<svg')
 
-    // Should have aria-describedby pointing to the code element ID
     expect(output).toContain('aria-describedby=')
   })
 })
diff --git a/src/content-render/types.ts b/src/content-render/types.ts
index 1f01894583a0..b23e94106e9f 100644
--- a/src/content-render/types.ts
+++ b/src/content-render/types.ts
@@ -1,10 +1,3 @@
-/**
- * Types for the content-render module
- */
-
-/**
- * Context interface for content rendering operations
- */
 export interface Context {
   currentLanguage?: string
   autotitleLanguage?: string
@@ -20,9 +13,6 @@ export interface Context {
   [key: string]: unknown
 }
 
-/**
- * Options for rendering operations
- */
 export interface RenderOptions {
   cache?: boolean | ((template: string, context: Context) => string | null)
   filename?: string
@@ -30,22 +20,13 @@ export interface RenderOptions {
   [key: string]: unknown
 }
 
-/**
- * Unified processor plugin function type
- */
 export type UnifiedPlugin = (context?: Context) => unknown
 
-/**
- * VFile interface for unified processing
- */
 export interface VFile {
   toString(): string
   [key: string]: unknown
 }
 
-/**
- * Unified processor interface
- */
 export interface UnifiedProcessor {
   process(content: string): Promise<VFile>
   use(plugin: unknown, ...args: unknown[]): UnifiedProcessor
diff --git a/src/content-render/unified/annotate.ts b/src/content-render/unified/annotate.ts
index 3b0c98272c33..120acb615e87 100644
--- a/src/content-render/unified/annotate.ts
+++ b/src/content-render/unified/annotate.ts
@@ -134,17 +134,13 @@ function createAnnotatedNode(node: ElementNode, context: Context): Element {
   const lang = node.children[0].properties!.className![0].replace('language-', '')
   const code = node.children[0].children![0].value as string
 
-  // Check the code is parse-able
   validate(lang, code)
 
-  // Group into code and notes
   const lines = code.split('\n').filter(hasChar)
   const groups = chunkBy(lines, matchComment(lang))
 
-  // Group groups into rows
   const rows = chunk(groups, 2)
 
-  // Check the rows are formatted correctly
   for (const [note, codeBlock] of rows) {
     if (note === undefined || codeBlock === undefined) {
       throw new Error(
@@ -153,7 +149,6 @@ function createAnnotatedNode(node: ElementNode, context: Context): Element {
     }
   }
 
-  // Render the HTML
   return template({ lang, code, rows, context })
 }
 
@@ -278,20 +273,16 @@ function template({
 function mdToHast(text: string, context: Context): Nodes {
   const mdast: Root = fromMarkdown(text)
 
-  // Process AUTOTITLE links
   processAutotitleInMdast(mdast, context)
 
   return toHast(mdast)
 }
 
-// Helper method to process AUTOTITLE links in MDAST
-// This can be reused for other MDAST processing that needs AUTOTITLE support
 function processAutotitleInMdast(mdast: Root, context: Context): void {
   visit(mdast, 'link', (node) => {
     if (node.url && node.url.startsWith('/')) {
       for (const child of node.children) {
         if (child.type === 'text' && /^\s*AUTOTITLE\s*$/.test(child.value)) {
-          // Find the page and get its title
           const page = findPage(node.url, context.pages, context.redirects)
           if (page) {
             try {
diff --git a/src/content-render/unified/collect-mini-toc.ts b/src/content-render/unified/collect-mini-toc.ts
index bbd8b8a82722..de6be1a1d569 100644
--- a/src/content-render/unified/collect-mini-toc.ts
+++ b/src/content-render/unified/collect-mini-toc.ts
@@ -64,7 +64,6 @@ const collectMiniToc: Plugin<[CollectMiniTocOptions], Root> = ({ collectInto })
 
       const title = textChildren.map((child) => toString(child)).join('')
 
-      // Detect platform from ghd-tool ancestor
       let platform = ''
       for (const anc of ancestors) {
         if (anc.type === 'element' && hasClassName(anc as Element, 'ghd-tool')) {
diff --git a/src/content-render/unified/copilot-prompt.ts b/src/content-render/unified/copilot-prompt.ts
index 6b8e463e48ba..69eb3b7b7236 100644
--- a/src/content-render/unified/copilot-prompt.ts
+++ b/src/content-render/unified/copilot-prompt.ts
@@ -47,7 +47,6 @@ function buildPromptData(
   tree: Root,
   code: string,
 ): { promptContent: string; ariaLabel: string } {
-  // Find a ref meta in the format 'ref=<id>'
   const ref = getPreMeta(node).ref
 
   if (!ref) {
diff --git a/src/content-render/unified/module-types.d.ts b/src/content-render/unified/module-types.d.ts
index 60c0cf6d00a9..298ecdc023c5 100644
--- a/src/content-render/unified/module-types.d.ts
+++ b/src/content-render/unified/module-types.d.ts
@@ -1,7 +1,3 @@
-/**
- * Type declarations for modules without TypeScript definitions
- */
-
 declare module 'remark-gemoji-to-emoji' {
   import type { Plugin } from 'unified'
   const plugin: Plugin
diff --git a/src/content-render/unified/rewrite-local-links.ts b/src/content-render/unified/rewrite-local-links.ts
index 6596969de7f4..727ccef09a8e 100644
--- a/src/content-render/unified/rewrite-local-links.ts
+++ b/src/content-render/unified/rewrite-local-links.ts
@@ -278,13 +278,11 @@ function getNewHref(node: LinkNode, languageCode: string, version: string): stri
     // start clean with no language (TOC pages already include the lang codes via lib/liquid-tags/link.ts)
     const hrefWithoutLang = getPathWithoutLanguage(url)
 
-    // normalize any legacy links so they conform to new link structure
     newHref = path.posix.join('/', languageCode, getNewVersionedPath(hrefWithoutLang))
 
-    // get the current version from the link
     const versionFromHref = getVersionStringFromPath(newHref)
 
-    // ------ BEGIN ONE-OFF OVERRIDES ------//
+    // One-off overrides:
     // desktop links always point to dotcom
     if (patterns.desktop.test(hrefWithoutLang)) {
       version = nonEnterpriseDefaultVersion
@@ -294,9 +292,7 @@ function getNewHref(node: LinkNode, languageCode: string, version: string): stri
     if (patterns.adminProduct.test(hrefWithoutLang) && version === nonEnterpriseDefaultVersion) {
       version = 'enterprise-cloud@latest'
     }
-    // ------ END ONE-OFF OVERRIDES ------//
 
-    // update the version in the link
     newHref = newHref.replace(versionFromHref, version)
   }
   newHref = removeFPTFromPath(newHref)
diff --git a/src/content-render/unified/rewrite-table-captions.ts b/src/content-render/unified/rewrite-table-captions.ts
index aa898ee8ddc5..2c4fdd3b1d4b 100644
--- a/src/content-render/unified/rewrite-table-captions.ts
+++ b/src/content-render/unified/rewrite-table-captions.ts
@@ -3,11 +3,9 @@ import type { Node, Parent } from 'unist'
 import type { Element, Text } from 'hast'
 
 /**
- * A rehype plugin that automatically adds aria-labelledby attributes to tables
- * based on their preceding headings for accessibility.
- *
- * This plugin improves table accessibility by ensuring screen readers can
- * announce table names when users navigate with the 'T' shortcut key.
+ * Adds aria-labelledby to tables, pointing at the nearest preceding heading,
+ * so screen readers announce a table name when users navigate with the 'T'
+ * shortcut key.
  *
  * Transforms this structure:
  *
@@ -24,12 +22,6 @@ import type { Element, Text } from 'hast'
  *     <thead>...</thead>
  *     <tbody>...</tbody>
  *   </table>
- *
- * The plugin works by:
- * 1. Finding table elements in the HTML AST
- * 2. Looking backwards for the nearest preceding heading with an id
- * 3. Adding aria-labelledby attribute pointing to that heading's id
- * 4. Skipping tables that already have accessibility attributes
  */
 
 interface HeadingInfo {
@@ -67,12 +59,10 @@ function hasExistingCaption(tableNode: Element): boolean {
 function findPrecedingHeading(parent: Parent, tableIndex: number): HeadingInfo | null {
   if (!parent.children || tableIndex === 0) return null
 
-  // Look backwards from the table position for the nearest heading
   for (let i = tableIndex - 1; i >= 0; i--) {
     const node = parent.children[i]
 
     if (isHeadingElement(node)) {
-      // Check if the heading has an id attribute
       const headingId = node.properties?.id
       if (headingId) {
         return {
@@ -122,13 +112,11 @@ export default function addTableAccessibilityLabels() {
         return
       }
 
-      // Find the preceding heading
       const precedingHeading = findPrecedingHeading(parent, index)
       if (!precedingHeading) {
         return
       }
 
-      // Add aria-labelledby attribute to the table
       if (!node.properties) {
         node.properties = {}
       }
diff --git a/src/content-render/unified/text-only.ts b/src/content-render/unified/text-only.ts
index d0a581c37ed8..2f9e6a9b25ff 100644
--- a/src/content-render/unified/text-only.ts
+++ b/src/content-render/unified/text-only.ts
@@ -1,7 +1,6 @@
 import { decode } from 'html-entities'
 
 // Strip all HTML tags, leaving only text content.
-// Handles nested tags like `<p>text with <code>code</code></p>`.
 const TAG_RE = /<[^>]+>/g
 
 // Given a piece of HTML return it without HTML. E.g.
diff --git a/src/content-render/unified/use-english-headings.ts b/src/content-render/unified/use-english-headings.ts
index 0109be6be74a..b48fcd1f9044 100644
--- a/src/content-render/unified/use-english-headings.ts
+++ b/src/content-render/unified/use-english-headings.ts
@@ -17,13 +17,9 @@ export default function useEnglishHeadings({ englishHeadings }: UseEnglishHeadin
     visit(tree, 'element', (node: Element) => {
       if (!['h2', 'h3', 'h4'].includes(node.tagName)) return
       slugger.reset()
-      // Get the plain text content of the heading node
       const text: string = toString(node)
-      // find English heading in the collection
       const englishHeading: string = englishHeadings[encode(text)]
-      // get English slug
       const englishSlug: string = slugger.slug(englishHeading)
-      // use English slug for heading ID and link
       if (englishSlug) {
         // only use English slug if there is one, otherwise we'll end up with
         // empty IDs

From 74c7d20adc810372f672934ecbf29b93d9096b07 Mon Sep 17 00:00:00 2001
From: Kevin Heis <heiskr@users.noreply.github.com>
Date: Tue, 15 Sep 2026 21:55:23 +0000
Subject: [PATCH 16/16] Trim excessive comments in src/frame/middleware
 (#63259)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: heiskr <1221423+heiskr@users.noreply.github.com>
Copilot-Session: 17588eeb-788a-4f82-9d36-b5079fb36521
---
 src/frame/lib/permalink.ts                    |  2 +-
 src/frame/lib/read-file-contents.ts           |  3 --
 src/frame/lib/read-frontmatter.ts             |  2 +-
 src/frame/lib/strip-outer-tag.ts              |  1 -
 src/frame/lib/warm-server.ts                  |  8 +---
 src/frame/middleware/abort.ts                 |  1 -
 src/frame/middleware/api.ts                   |  1 -
 src/frame/middleware/cache-control.ts         |  2 +-
 src/frame/middleware/context/context.ts       | 12 ++---
 .../context/current-product-tree.ts           |  2 +-
 src/frame/middleware/context/generic-toc.ts   | 13 ++----
 .../middleware/context/product-groups.ts      |  2 +-
 src/frame/middleware/cookie-parser.ts         |  9 ++--
 src/frame/middleware/find-page.ts             |  3 --
 src/frame/middleware/healthcheck.ts           | 11 ++---
 src/frame/middleware/helmet.ts                |  3 +-
 src/frame/middleware/index.ts                 |  4 +-
 src/frame/middleware/mock-va-portal.ts        | 27 +++++------
 src/frame/middleware/next.ts                  |  6 +--
 src/frame/middleware/reload-tree.ts           | 25 ++++------
 src/frame/middleware/render-page.ts           | 46 ++++++++-----------
 src/frame/middleware/resolve-carousels.ts     | 19 +-------
 src/frame/middleware/url-decode.ts            | 12 ++---
 src/frame/pages/app.tsx                       | 10 ++--
 src/frame/start-server.ts                     |  1 -
 25 files changed, 77 insertions(+), 148 deletions(-)

diff --git a/src/frame/lib/permalink.ts b/src/frame/lib/permalink.ts
index c6970471d923..1b45b496bde6 100644
--- a/src/frame/lib/permalink.ts
+++ b/src/frame/lib/permalink.ts
@@ -29,7 +29,7 @@ page.permalinks is an array of objects that looks like this:
 */
 // String interning pool: deduplicates low-cardinality, highly-repeated values (languageCode, pageVersion)
 // across ~975K Permalink instances (~9 languages × ~9 versions × ~65K pages). Because these fields have
-// few distinct values (~81 total), the pool stays bounded — do not use intern() for high-cardinality
+// few distinct values (~81 total), the pool stays bounded. Do not use intern() for high-cardinality
 // fields like relativePath or title, where the pool would grow unbounded and leak memory.
 const stringPool = new Map<string, string>()
 
diff --git a/src/frame/lib/read-file-contents.ts b/src/frame/lib/read-file-contents.ts
index f608a8d7b9e3..9c45abc0e30e 100644
--- a/src/frame/lib/read-file-contents.ts
+++ b/src/frame/lib/read-file-contents.ts
@@ -7,9 +7,6 @@ import fm from './frontmatter'
 const fmCache =
   process.env.NODE_ENV === 'production' ? new Map<string, ReturnType<typeof fm>>() : null
 
-/**
- * Read only the frontmatter from  file
- */
 export default async function fmfromf(filepath: string): Promise<ReturnType<typeof fm>> {
   const cached = fmCache?.get(filepath)
   if (cached) return cached
diff --git a/src/frame/lib/read-frontmatter.ts b/src/frame/lib/read-frontmatter.ts
index ceb62c683102..aa6d60209798 100644
--- a/src/frame/lib/read-frontmatter.ts
+++ b/src/frame/lib/read-frontmatter.ts
@@ -56,7 +56,7 @@ function readFrontmatter(markdown: string, opts: ReadFrontmatterOptions = {}) {
   // return:
   //   property: 'versions.ftp'
   //
-  // The purpose is to help users understand that the error is on the `fpt` key within the `versions` object.
+  // The purpose is to help users understand that the error is on the `ftp` key within the `versions` object.
   // Note if the error is on a top-level FM property like `title`, the `instancePath` will be empty.
   const cleanPropertyPath = (
     params: Record<string, unknown>,
diff --git a/src/frame/lib/strip-outer-tag.ts b/src/frame/lib/strip-outer-tag.ts
index 371069b14a72..27f2caf6ee01 100644
--- a/src/frame/lib/strip-outer-tag.ts
+++ b/src/frame/lib/strip-outer-tag.ts
@@ -5,7 +5,6 @@
 export function stripOuterTag(html: string): string {
   if (!html) return ''
 
-  // Extract opening tag and tag name
   const openMatch = html.match(/^<([a-z][a-z0-9]*)\b[^>]*>/i)
   if (!openMatch) return html
 
diff --git a/src/frame/lib/warm-server.ts b/src/frame/lib/warm-server.ts
index 71b2b13cb88a..98b806f8e629 100644
--- a/src/frame/lib/warm-server.ts
+++ b/src/frame/lib/warm-server.ts
@@ -14,8 +14,7 @@ type WarmServerResult = {
   pageMap: Awaited<ReturnType<typeof loadPageMap>>
 }
 
-// Instrument these functions so that
-// it's wrapped in a timer that reports to Datadog
+// Wrap these functions in timers that report to Datadog.
 const dog = {
   loadUnversionedTree: statsd.asyncTimer(
     adaptForTimer(loadUnversionedTree),
@@ -28,7 +27,6 @@ const dog = {
   warmServer: statsd.asyncTimer(adaptForTimer(warmServer), 'warm_server'),
 }
 
-// For multiple-triggered Promise sharing
 let promisedWarmServer: Promise<WarmServerResult> | undefined
 
 async function warmServer(languagesOnly: string[] = []): Promise<WarmServerResult> {
@@ -94,10 +92,6 @@ async function warmServer(languagesOnly: string[] = []): Promise<WarmServerResul
   }
 }
 
-// Instrument the `warmServer` function so that
-// it's wrapped in a timer that reports to Datadog
-// dog.warmServer = statsd.asyncTimer(warmServer, 'warm_server') as typeof warmServer
-
 // We only want statistics if the priming needs to occur, so let's wrap the
 // real method and return early [without statistics] whenever possible
 export default async function warmServerWrapper(languagesOnly: string[] = []) {
diff --git a/src/frame/middleware/abort.ts b/src/frame/middleware/abort.ts
index c90ca8e5aa85..e9f9496578ed 100644
--- a/src/frame/middleware/abort.ts
+++ b/src/frame/middleware/abort.ts
@@ -36,7 +36,6 @@ export default function abort(req: ExtendedRequest, res: Response, next: NextFun
 
     const abortError = new AbortError('Client closed request', 499, 'ECONNRESET')
 
-    // Pass the error to the Express error handler
     return next(abortError)
   })
 
diff --git a/src/frame/middleware/api.ts b/src/frame/middleware/api.ts
index cf723206b464..a7c3f1acb7ac 100644
--- a/src/frame/middleware/api.ts
+++ b/src/frame/middleware/api.ts
@@ -63,7 +63,6 @@ router.get('/cookies', (req, res) => {
   res.json(cookies)
 })
 
-// Handle root /api requests
 router.get('/', (req, res) => {
   res.status(404).json({ error: `${req.path} not found` })
 })
diff --git a/src/frame/middleware/cache-control.ts b/src/frame/middleware/cache-control.ts
index b06f97b13c76..b53e5ca98364 100644
--- a/src/frame/middleware/cache-control.ts
+++ b/src/frame/middleware/cache-control.ts
@@ -53,7 +53,7 @@ function cacheControlFactory(
   }
 }
 
-// ### These are roughly in order from shortest to longest. ###
+// The rest of this file is roughly in order from shortest max age to longest.
 
 // If you do not want caching.
 export const noCacheControl = cacheControlFactory(0)
diff --git a/src/frame/middleware/context/context.ts b/src/frame/middleware/context/context.ts
index e3bda46dc802..7d0e0390b1da 100644
--- a/src/frame/middleware/context/context.ts
+++ b/src/frame/middleware/context/context.ts
@@ -91,14 +91,12 @@ export default async function contextualize(
   const restDate = new Date(req.context.initialRestVersioningReleaseDate)
   req.context.initialRestVersioningReleaseDateLong = restDate.toUTCString().split(' 00:')[0]
 
-  // Conditionally add this for non-English pages so what inside the
-  // `Page.render` method, when it calls out to `renderContentWithFallback`
-  // it can be able to fall back get original content from English if there's
-  // some runtime rendering error from the translation.
+  // Non-English pages need this so that `Page.render`, when it calls
+  // `renderContentWithFallback`, can fall back to the English content when the
+  // translation hits a fallback-eligible error (Liquid, autotitle, empty title).
   if (req.language !== 'en') {
-    // The reason this is a function is because most of the time, we don't
-    // need to know the English equivalent. It only comes into play if a
-    // translated
+    // This is a function so the lookup only happens when a translated page
+    // actually needs to fall back. Most requests never need it.
     req.context.getEnglishPage = (ctx) => {
       if (!ctx.enPage) {
         const { page } = ctx
diff --git a/src/frame/middleware/context/current-product-tree.ts b/src/frame/middleware/context/current-product-tree.ts
index 855e81f99eb4..1a34c3015c83 100644
--- a/src/frame/middleware/context/current-product-tree.ts
+++ b/src/frame/middleware/context/current-product-tree.ts
@@ -49,7 +49,7 @@ export default async function currentProductTree(
     req.context,
   )
   // Now make an even slimmer version that excludes all hidden pages.
-  // This is i used for sidebars.
+  // This is used for sidebars.
   req.context.currentProductTreeTitlesExcludeHidden = excludeHidden(
     req.context.currentProductTreeTitles,
   )
diff --git a/src/frame/middleware/context/generic-toc.ts b/src/frame/middleware/context/generic-toc.ts
index 580e6159ba91..93a57bf99f91 100644
--- a/src/frame/middleware/context/generic-toc.ts
+++ b/src/frame/middleware/context/generic-toc.ts
@@ -31,10 +31,8 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
   )
     return next()
 
-  // This one product TOC is weird.
   const isOneOffProductToc = req.context.page.relativePath === 'github/index.md'
 
-  // There are different types of TOC depending on the document type.
   const tocTypes: Record<string, string> = {
     product: 'flat',
     category: 'nested',
@@ -49,21 +47,22 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
   if (!req.context.currentEnglishTree) throw new Error('currentEnglishTree not in context')
   if (!req.pagePath) throw new Error('pagePath not in request')
 
-  // Find the part of the site tree that corresponds to the current path.
   const treePage = findPageInSiteTree(
     req.context.currentProductTree,
     req.context.currentEnglishTree,
     req.pagePath,
   )
 
+  // The intent is that a category whose children have no children of their own
+  // should render like a subcategory. It doesn't work: `child.children` is `[]`
+  // for leaf pages and `[]` is truthy, so `hasGrandchildren` is true for any
+  // category with children at all. This probably wants `child.children?.length`.
   let fauxSubcategory = false
   if (req.context.page.documentType === 'category' && req.context.page.autogenerated !== 'rest') {
-    // But does *have* children?
     const hasGrandchildren = (treePage.childPages || []).some((child) => child.children)
     fauxSubcategory = !hasGrandchildren
   }
 
-  // Find the current TOC type based on the current document type.
   const currentTocType = earlyAccessToc
     ? 'nested'
     : fauxSubcategory
@@ -83,9 +82,7 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
   const includeHidden =
     earlyAccessToc || (isCategoryOrSubcategory && isEarlyAccess && !isArticlesCategory)
 
-  // Conditionally run getTocItems() recursively.
   let isRecursive
-  // Conditionally render intros.
   let renderIntros
 
   // Get an array of child links with intros and add it to the context object.
@@ -115,8 +112,6 @@ export default async function genericToc(req: ExtendedRequest, res: Response, ne
   return next()
 }
 
-// Return a nested object that contains the bits and pieces we need
-// for the tree which is used for sidebars and listing
 type Options = {
   recurse: boolean
   renderIntros: boolean
diff --git a/src/frame/middleware/context/product-groups.ts b/src/frame/middleware/context/product-groups.ts
index e6f8e4d8f2ac..6a9427277394 100644
--- a/src/frame/middleware/context/product-groups.ts
+++ b/src/frame/middleware/context/product-groups.ts
@@ -28,7 +28,7 @@ export default async function productGroups(
   if (!req.context) throw new Error('request is not contextualized')
   if (!req.pagePath) throw new Error('pagePath is not set on request')
   if (!req.language) throw new Error('language is not set on request')
-  // It's important to use `req.pathPage` instead of `req.path` because
+  // It's important to use `req.pagePath` instead of `req.path` because
   // the request could be the client-side routing from Next where the URL
   // might be something like `/_next/data/foo/bar.json` which is translated,
   // in another middleware, to what it would equate to if it wasn't
diff --git a/src/frame/middleware/cookie-parser.ts b/src/frame/middleware/cookie-parser.ts
index 1d17cf6786a3..ffe82e348ba0 100644
--- a/src/frame/middleware/cookie-parser.ts
+++ b/src/frame/middleware/cookie-parser.ts
@@ -5,11 +5,8 @@ import { cookieSettings } from '@/frame/lib/cookie-settings'
 
 export default cookieParser(
   process.env.COOKIE_SECRET,
-  // This is because of a but in @types/cookie-parser
-  // The options are actually passed straight into `cookie.parse`
-  // from the cookie page. When creating a cookie setting object in
-  // our `cookie-settings.ts` we want to use the right type,
-  // which is `CookieSerializeOptions` (from the `cookie` package)
-  // but we have circumnavigate the option here.
+  // `cookie-settings.ts` declares these as `CookieSerializeOptions` because
+  // that is the right type for the places that set cookies. cookie-parser
+  // wants `CookieParseOptions`, so bridge the two here.
   cookieSettings as CookieParseOptions,
 )
diff --git a/src/frame/middleware/find-page.ts b/src/frame/middleware/find-page.ts
index 4b384444485f..7f606fc4abb4 100644
--- a/src/frame/middleware/find-page.ts
+++ b/src/frame/middleware/find-page.ts
@@ -35,7 +35,6 @@ export default async function findPage(
     return next()
   }
 
-  // Using any for page because it's dynamically assigned properties (like version) that aren't in the Page type
   let page = req.context.pages[req.pagePath] as Page | undefined
   if (page && isDev && englishPrefixRegex.test(req.pagePath)) {
     // The .applicableVersions and .permalinks properties are computed
@@ -79,14 +78,12 @@ export default async function findPage(
 
   if (page && req.context) {
     req.context.page = page
-    // Note: Page doesn't have a version property, this might be setting it dynamically
     ;(req.context.page as Page & { version: string }).version = req.context.currentVersion || ''
 
     // We can't depend on `page.hidden` because the dedicated search
     // results page is a hidden page but it needs to offer all possible
     // languages.
     if (page.relativePath.startsWith('early-access') && req.context?.languages?.en) {
-      // Override the languages to be only English
       req.context.languages = {
         en: req.context.languages.en,
       }
diff --git a/src/frame/middleware/healthcheck.ts b/src/frame/middleware/healthcheck.ts
index e2c8d228e4ac..68e3089b17d5 100644
--- a/src/frame/middleware/healthcheck.ts
+++ b/src/frame/middleware/healthcheck.ts
@@ -4,12 +4,11 @@ import statsd from '@/observability/lib/statsd'
 
 const router = express.Router()
 
-/**
- * Returns the healthiness of the service.
- * This may be used by Moda to determine whether this
- * instance remains in the pool to handle requests
- * For example: if we have a failing database connection we may return a 500 status here.
- */
+// Returns the healthiness of the service.
+// Moda may use this to decide whether this instance stays in the pool.
+// Today it checks nothing and always returns 200. If we ever needed to drain
+// an instance, for example on a failing dependency, this is where a 500
+// would go.
 router.get('/', function healthcheck(req, res) {
   noCacheControl(res)
 
diff --git a/src/frame/middleware/helmet.ts b/src/frame/middleware/helmet.ts
index 6e7e1b1501d4..ddbd4b90e8a1 100644
--- a/src/frame/middleware/helmet.ts
+++ b/src/frame/middleware/helmet.ts
@@ -57,7 +57,8 @@ const DEFAULT_OPTIONS = {
       frameSrc: [
         ...GITHUB_DOMAINS,
         isDev && 'http://localhost:3000',
-        // This URL is also set in ArticleContext.tsx. We don't rely on importing a constant as we may run into an import conflict where the env variable is not yet set.
+        // ArticleContext.tsx sets this URL too. We don't import a shared
+        // constant because the env var may not be set yet at import time.
         process.env.NODE_ENV === 'production'
           ? 'https://support.github.com'
           : // Assume that a developer is not testing the VA iframe locally if this env var is not set
diff --git a/src/frame/middleware/index.ts b/src/frame/middleware/index.ts
index 0d7e1d2985e8..d4070063dd82 100644
--- a/src/frame/middleware/index.ts
+++ b/src/frame/middleware/index.ts
@@ -201,8 +201,6 @@ export default function index(app: Express) {
     app.use(mockVaPortal) // FOR TESTING.
   }
 
-  // ** Possible early exits after cookies **
-
   // *** Headers ***
   app.set('etag', false) // We will manage our own ETags if desired
 
@@ -216,7 +214,7 @@ export default function index(app: Express) {
   app.use(asyncMiddleware(renderProductName)) // Must come after shortVersions
 
   // Must come before handleRedirects.
-  // This middleware might either redirect to serve something.
+  // This middleware might either redirect or serve something.
   app.use(asyncMiddleware(archivedEnterpriseVersions))
 
   // *** Redirects, 3xx responses ***
diff --git a/src/frame/middleware/mock-va-portal.ts b/src/frame/middleware/mock-va-portal.ts
index dc98dcc4468b..cafc8781dc4d 100644
--- a/src/frame/middleware/mock-va-portal.ts
+++ b/src/frame/middleware/mock-va-portal.ts
@@ -1,18 +1,15 @@
-/**
- * To test the VA integration, we need to mock the VA portal.
- * This is if you don't have access to the VA portal in a staging environment.
- * And you can't use the VA portal in production, because that one is
- * hardened to only use https://docs.github.com, not your localhost:4000.
- *
- * So, to test this locally, you need to:
- *
- *   1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` into your `.env` file
- *   2. `npm run dev`
- *   3. Navigate to a page whose path is mentioned in the
- *      `PagePathToVaFlowMapping` object in the `ArticleContext`.
- *
- * This mocking is not secure, but it's only for local development.
- */
+// Mocks the VA portal so you can test the VA integration without access to a
+// staging VA portal. You can't point at the production one either, because it
+// is hardened to https://docs.github.com and will reject your localhost:4000.
+//
+// To test locally:
+//
+//   1. Add `SUPPORT_PORTAL_URL=http://localhost:4000` to your `.env` file
+//   2. `npm run dev`
+//   3. Navigate to a page listed in the `PagePathToVaFlowMapping` object in
+//      the `ArticleContext`.
+//
+// This mocking is not secure. It is only for local development.
 
 import type { Response, NextFunction } from 'express'
 
diff --git a/src/frame/middleware/next.ts b/src/frame/middleware/next.ts
index ebe123a365e1..bc50942ffeae 100644
--- a/src/frame/middleware/next.ts
+++ b/src/frame/middleware/next.ts
@@ -12,14 +12,12 @@ export const nextHandleRequest = nextApp.getRequestHandler()
 await nextApp.prepare()
 
 function renderPageWithNext(req: ExtendedRequest, res: Response, nextFn: NextFunction) {
+  // This catches URLs like `/_next/webpack-hmr` and
+  // `/_next/static/webpack/64e44ef62e261d3a.webpack.hot-update.json`.
   if (req.path.startsWith('/_next') && !req.path.startsWith('/_next/data')) {
     return nextHandleRequest(req, res)
   }
 
-  // Note that URLs like `/_next/webpack-hmr` and
-  // '/_next/static/webpack/64e44ef62e261d3a.webpack.hot-update.json' has to
-  // go through here.
-
   return nextFn()
 }
 
diff --git a/src/frame/middleware/reload-tree.ts b/src/frame/middleware/reload-tree.ts
index 2f1c4ff9a4df..3007311e64c4 100644
--- a/src/frame/middleware/reload-tree.ts
+++ b/src/frame/middleware/reload-tree.ts
@@ -1,18 +1,13 @@
-/**
- * This exists for local reviewing. Only.
- * We load in the entire tree on startup, then that's used for things like
- * sidebars and breadcrumbs and landing pages and ToC pages (and possibly
- * more).
- * When an individual page is requested, we always reload it from disk
- * in case it has changed. But that's not feasible with all 1k+ pages.
- *
- * The core of this middleware calls `createTree()` but by passing the
- * optional previous tree so that within `createTree` it can opt to
- * re-use those that haven't changed on disk.
- *
- * The intention here is so that things like sidebars can refresh
- * without having to restart the entire server.
- */
+// This exists for local reviewing only.
+//
+// We load the entire tree on startup and use it for sidebars, breadcrumbs,
+// landing pages, and ToC pages. In development, an individual English page is
+// reread from disk on each request in case it changed, but doing that for all
+// 1k+ pages is not feasible.
+//
+// So this middleware calls `createTree()` with the previous tree, letting
+// `createTree` reuse the pages that haven't changed on disk. That way things
+// like sidebars refresh without restarting the server.
 
 import path from 'path'
 
diff --git a/src/frame/middleware/render-page.ts b/src/frame/middleware/render-page.ts
index fe6f585bfecd..0aed59fe722e 100644
--- a/src/frame/middleware/render-page.ts
+++ b/src/frame/middleware/render-page.ts
@@ -41,20 +41,16 @@ async function buildRenderedPage(req: ExtendedRequest): Promise<string> {
   return (await pageRenderTimed(context)) as string
 }
 
-/**
- * Spike for #6619 (remove dangerouslySetInnerHTML): produce the article body as
- * a serializable hast (HTML AST) tree alongside the legacy HTML string.
- *
- * Must run AFTER buildRenderedPage, which calls page.render and populates the
- * context fields the pipeline reads (englishHeadings, alertTitles). We render
- * the same raw `page.markdown`, but with a context clone that omits
- * `collectMiniToc` so the mini-TOC isn't collected a second time.
- *
- * Wrapped so a hast failure can never break the page: the React layer falls
- * back to the string path when this is undefined. NOTE: this currently renders
- * the body pipeline twice; the production design (see #6619 plan) should produce
- * hast once and derive the string from it.
- */
+// Spike for #6619: produce the article body as a serializable hast (HTML AST)
+// tree alongside the legacy HTML string.
+//
+// Must run AFTER buildRenderedPage, which calls page.render and populates the
+// context fields the pipeline reads (englishHeadings, alertTitles). We render
+// the same raw `page.markdown`, but with a context clone that omits
+// `collectMiniToc` so the mini-TOC isn't collected a second time.
+//
+// Wrapped so a hast failure can never break the page. The React layer falls
+// back to the string path when this is undefined.
 async function buildRenderedPageHast(req: ExtendedRequest) {
   const { context } = req
   if (!context) throw new Error('request not contextualized')
@@ -95,10 +91,8 @@ function buildMiniTocItems(req: ExtendedRequest) {
 export default async function renderPage(req: ExtendedRequest, res: Response) {
   const { context } = req
 
-  // This is a contextualizing the request so that when this `req` is
-  // ultimately passed into the `Error.getInitialProps` function,
-  // which NextJS executes at runtime on errors, so that we can
-  // from there send the error to Failbot.
+  // `Error.getInitialProps`, which NextJS runs on errors, reads this off the
+  // request so it can send the error to Failbot.
   req.FailBot = FailBot as Failbot
 
   if (!context) throw new Error('request not contextualized')
@@ -127,9 +121,8 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
   // Updating the Last-Modified header for substantive changes on a page for engineering
   // Docs Engineering Issue #945
   if (page.effectiveDate) {
-    // Note that if a page has an invalidate `effectiveDate` string value,
-    // it would be caught prior to this usage and ultimately lead to
-    // 500 error.
+    // The frontmatter schema only checks that this is a string. An unparseable
+    // date gets caught later, in ArticleContext, and ends up as a 500.
     res.setHeader('Last-Modified', new Date(page.effectiveDate).toUTCString())
   }
 
@@ -144,8 +137,8 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
   if (context.markdownRequested) {
     const transformer = transformerRegistry.findTransformer(page)
     if (!transformer) throw new Error(`No transformer found for page: ${req.pagePath}`)
-    // Pass context without markdownRequested — transformers set it themselves
-    // when rendering templates. Having it set during prepareTemplateData()
+    // Pass context without markdownRequested, because transformers set it
+    // themselves when rendering templates. Having it set during prepareTemplateData()
     // causes renderTitle/renderProp to output markdown instead of HTML,
     // which breaks the cheerio-based unwrap logic.
     const transformerContext = { ...context, markdownRequested: false }
@@ -158,7 +151,6 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
     req.context.miniTocItems = buildMiniTocItems(req)
   }
 
-  // Create string for <title> tag
   page.fullTitle = page.title
 
   // add localized ` - GitHub Docs` suffix to <title> tag (except for the homepage)
@@ -181,10 +173,8 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
     }
   }
 
-  // Is the request for JSON debugging info?
   const isRequestingJsonForDebugging = 'json' in req.query && process.env.NODE_ENV !== 'production'
 
-  // `?json` query param for debugging request context
   if (isRequestingJsonForDebugging) {
     const json = req.query.json
     if (Array.isArray(json)) {
@@ -207,10 +197,10 @@ export default async function renderPage(req: ExtendedRequest, res: Response) {
 
   if (context.markdownRequested) {
     if (context.markdownViaUrl) {
-      // .md URL suffix always returns markdown — Vary: accept would be misleading
+      // A .md URL suffix always returns markdown, so Vary: accept would mislead.
       defaultCacheControl(res)
     } else {
-      // Accept header determines the representation — Vary: accept is correct
+      // The Accept header picks the representation, so Vary: accept is correct.
       contentTypeCacheControl(res)
     }
     return res.type('text/markdown').send(req.context.renderedPage)
diff --git a/src/frame/middleware/resolve-carousels.ts b/src/frame/middleware/resolve-carousels.ts
index c079cb23aad8..2aa68876923b 100644
--- a/src/frame/middleware/resolve-carousels.ts
+++ b/src/frame/middleware/resolve-carousels.ts
@@ -14,18 +14,12 @@ interface PageCarouselProps {
 
 const logger = createLogger('middleware:resolve-carousels')
 
-/**
- * Build an article path by combining language, optional base path, and article path
- */
 function buildArticlePath(currentLanguage: string, articlePath: string, basePath?: string): string {
   const pathPrefix = basePath ? `/${currentLanguage}/${basePath}` : `/${currentLanguage}`
   const separator = articlePath.startsWith('/') ? '' : '/'
   return `${pathPrefix}${separator}${articlePath}`
 }
 
-/**
- * Try to resolve an article path using multiple resolution strategies
- */
 function tryResolveArticlePath(
   rawPath: string,
   pageRelativePath: string | undefined,
@@ -34,7 +28,6 @@ function tryResolveArticlePath(
   const { pages, redirects } = req.context!
   const currentLanguage = req.context!.currentLanguage || 'en'
 
-  // Check if we have the required dependencies
   if (!pages || !redirects) {
     return undefined
   }
@@ -89,19 +82,14 @@ function tryResolveArticlePath(
   return foundPage
 }
 
-/**
- * Get the path for a page (without language/version)
- */
+// Returns a page's path without the language or version prefix.
 function getPageHref(page: Page): string {
   if (page.relativePath) {
     return Permalink.relativePathToSuffix(page.relativePath)
   }
-  return '' // fallback
+  return ''
 }
 
-/**
- * Middleware to resolve carousel articles from rawCarousels object
- */
 async function resolveCarousels(
   req: ExtendedRequest,
   res: Response,
@@ -111,7 +99,6 @@ async function resolveCarousels(
     const page = req.context?.page
     const rawCarousels = (page as unknown as PageCarouselProps)?.rawCarousels
 
-    // Handle carousels format
     if (rawCarousels && typeof rawCarousels === 'object') {
       const resolvedCarousels: Record<string, ResolvedArticle[]> = {}
 
@@ -120,7 +107,6 @@ async function resolveCarousels(
           continue
         }
 
-        // Remove duplicate articles
         const uniquePaths = [...new Set(articlePaths)]
         const resolved: ResolvedArticle[] = []
 
@@ -162,7 +148,6 @@ async function resolveCarousels(
         }
       }
 
-      // Store resolved carousels on the page
       if (page && Object.keys(resolvedCarousels).length > 0) {
         ;(page as unknown as PageCarouselProps).carousels = resolvedCarousels
       }
diff --git a/src/frame/middleware/url-decode.ts b/src/frame/middleware/url-decode.ts
index bc3d2cc25c24..7e49a5e3f86f 100644
--- a/src/frame/middleware/url-decode.ts
+++ b/src/frame/middleware/url-decode.ts
@@ -1,23 +1,17 @@
 import type { NextFunction, Response } from 'express'
 import type { ExtendedRequest } from '@/types'
 
-/**
- * Middleware to decode URL-encoded @ symbols.
- *
- * SharePoint and other systems automatically encode @ symbols to %40,
- * which breaks our versioned URLs like /en/enterprise-cloud@latest.
- * This middleware decodes @ symbols anywhere in the URL.
- */
+// Decodes URL-encoded @ symbols anywhere in the URL.
+// SharePoint and other systems encode @ as %40, which breaks our versioned
+// URLs like /en/enterprise-cloud@latest.
 export default function urlDecode(req: ExtendedRequest, res: Response, next: NextFunction) {
   const originalUrl = req.url
 
-  // Only process URLs that contain %40 (encoded @)
   if (!originalUrl.includes('%40')) {
     return next()
   }
 
   try {
-    // Decode the entire URL, replacing %40 with @
     const decodedUrl = originalUrl.replace(/%40/g, '@')
     req.url = decodedUrl
     return next()
diff --git a/src/frame/pages/app.tsx b/src/frame/pages/app.tsx
index 2194586d2230..ff875377863d 100644
--- a/src/frame/pages/app.tsx
+++ b/src/frame/pages/app.tsx
@@ -46,12 +46,10 @@ const stagingNames = new Set([
 ])
 
 function getFaviconHref(stagingName?: string) {
-  /* The value in these "/cb-xxxxx" prefixes aren't important. They
-      just need to be present. They help the CDN cache the asset
-      for infinity.
-      Just remember, if you edit these images on disk, remember to
-      change these numbers
-   */
+  // The number in these "/cb-xxxxx" prefixes does not matter, it just has to be
+  // present. It marks the URL as checksummed, which gets it a manual Fastly
+  // surrogate key so a production deploy does not purge it.
+  // If you edit these images on disk, change the numbers.
   if (stagingName) {
     return `/assets/cb-345/images/site/evergreens/${stagingName}.png`
   }
diff --git a/src/frame/start-server.ts b/src/frame/start-server.ts
index 79ab75e9d57b..aa7021dd454a 100644
--- a/src/frame/start-server.ts
+++ b/src/frame/start-server.ts
@@ -33,7 +33,6 @@ export async function main() {
 }
 
 async function checkPortAvailability() {
-  // Check that the development server is not already running
   const portInUse = await tcpPortUsed.check(port)
   if (portInUse) {
     logger.error('Port is not available. You may already have a server running.', { port })