More code comments

lib/transform-js.js

@@ -25,8 +25,8 @@ export async function transformJs(jsPath, { dryRun, root } = {}) {
   }
   console.warn(`Using root: ${root}`)
 
+  // Parse the source JS, XHTML & .properties files
   const ast = jsParse(await readFile(jsPath, 'utf8'))
-
   const { properties, xhtml } = await findExternalRefs(root, ast)
 
   let hasPropMigrations = false
@@ -49,6 +49,8 @@ export async function transformJs(jsPath, { dryRun, root } = {}) {
   ])
   const bundlePaths = new Map() // ftlPath -> NodePath[]
 
+  // Replace all `Services.strings.createBundle()` calls &
+  // `<stringbundle>` getters with `new Localization()` calls.
   visit(ast, {
     visitCallExpression(path) {
       this.traverse(path)
@@ -109,6 +111,7 @@ export async function transformJs(jsPath, { dryRun, root } = {}) {
     ['getFormattedString', 2] // <stringbundle>
   ])
 
+  // Replace all old-API formatting method calls with Localization calls
   let requiresSync = false
   const msgKeyLiterals = new Map()
   const fmtArgObjects = new Set()
@@ -158,6 +161,7 @@ export async function transformJs(jsPath, { dryRun, root } = {}) {
     }
   })
 
+  // Dedupe bundle constructor calls, setting them sync if required
   for (const [ftlPath, nodePaths] of bundlePaths.entries()) {
     if (nodePaths.length === 1) {
       if (requiresSync) nodePaths[0].node.arguments[1] = b.literal(true)
@@ -172,6 +176,7 @@ export async function transformJs(jsPath, { dryRun, root } = {}) {
     }
   }
 
+  // Add L10N-FIXME comments to places that need human attention
   const fixmeLines = new Set()
   if (fixmeNodes.size > 0) {
     for (const node of fixmeNodes) {
@@ -293,6 +298,10 @@ function findSourceLiteral(path) {
   return null
 }
 
+/**
+ * Finds the array defining the parameters, and transforms it into an object.
+ * On success, returns the node to include as the formatter argument.
+ */
 function fixFormatterArgs(done, path) {
   const arg = path.node
   if (!arg || done.has(arg)) return arg