refactor(migrations): code clean up and add comments on exported functions (#52755)

This cleans up a bit of code to make maintenance easier. It also adds comments for all the exported methods so they are clear to anyone in the future.

PR Close #52755

packages/core/schematics/ng-generate/control-flow-migration/ifs.ts

@@ -64,7 +64,7 @@ export function migrateIf(template: string): {migrated: string, errors: MigrateE
   return {migrated: result, errors};
 }
 
-export function migrateNgIf(etm: ElementToMigrate, tmpl: string, offset: number): Result {
+function migrateNgIf(etm: ElementToMigrate, tmpl: string, offset: number): Result {
   const matchThen = etm.attr.value.match(/;\s*then/gm);
   const matchElse = etm.attr.value.match(/;\s*else/gm);
 

packages/core/schematics/ng-generate/control-flow-migration/index.ts

@@ -13,11 +13,9 @@ import {normalizePath} from '../../utils/change_tracker';
 import {getProjectTsConfigPaths} from '../../utils/project_tsconfig_paths';
 import {canMigrateFile, createMigrationProgram} from '../../utils/typescript/compiler_host';
 
-import {migrateFor} from './fors';
-import {migrateIf} from './ifs';
-import {migrateSwitch} from './switches';
+import {migrateTemplate} from './migration';
 import {AnalyzedFile, MigrateError} from './types';
-import {analyze, processNgTemplates} from './util';
+import {analyze} from './util';
 
 interface Options {
   path: string;
@@ -88,17 +86,7 @@ function runControlFlowMigration(
       const template = content.slice(start, end);
       const length = (end ?? content.length) - start;
 
-      const ifResult = migrateIf(template);
-      const forResult = migrateFor(ifResult.migrated);
-      const switchResult = migrateSwitch(forResult.migrated);
-
-      const errors = [
-        ...ifResult.errors,
-        ...forResult.errors,
-        ...switchResult.errors,
-      ];
-
-      const migrated = processNgTemplates(switchResult.migrated);
+      const {migrated, errors} = migrateTemplate(template);
 
       if (migrated !== null) {
         update.remove(start, length);

packages/core/schematics/ng-generate/control-flow-migration/migration.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {migrateFor} from './fors';
+import {migrateIf} from './ifs';
+import {migrateSwitch} from './switches';
+import {MigrateError} from './types';
+import {processNgTemplates} from './util';
+
+/**
+ * Actually migrates a given template to the new syntax
+ */
+export function migrateTemplate(template: string): {migrated: string, errors: MigrateError[]} {
+  const ifResult = migrateIf(template);
+  const forResult = migrateFor(ifResult.migrated);
+  const switchResult = migrateSwitch(forResult.migrated);
+
+  const migrated = processNgTemplates(switchResult.migrated);
+
+  const errors = [
+    ...ifResult.errors,
+    ...forResult.errors,
+    ...switchResult.errors,
+  ];
+  return {migrated, errors};
+}

packages/core/schematics/ng-generate/control-flow-migration/types.ts

@@ -75,6 +75,9 @@ export class ElementToMigrate {
   }
 }
 
+/**
+ * Represents an ng-template inside a template being migrated to new control flow
+ */
 export class Template {
   el: Element;
   count: number = 0;

packages/core/schematics/ng-generate/control-flow-migration/util.ts

@@ -82,6 +82,9 @@ function getNestedCount(etm: ElementToMigrate, aggregator: number[]) {
   }
 }
 
+/**
+ * parses the template string into the Html AST
+ */
 export function parseTemplate(template: string): ParseTreeResult|null {
   let parsed: ParseTreeResult;
   try {
@@ -108,6 +111,9 @@ export function parseTemplate(template: string): ParseTreeResult|null {
   return parsed;
 }
 
+/**
+ * calculates the level of nesting of the items in the collector
+ */
 export function calculateNesting(
     visitor: ElementCollector|TemplateCollector, hasLineBreaks: boolean): void {
   // start from top of template
@@ -133,10 +139,16 @@ function escapeRegExp(val: string) {
   return val.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');  // $& means the whole matched string
 }
 
+/**
+ * determines if a given template string contains line breaks
+ */
 export function hasLineBreaks(template: string): boolean {
   return /\r|\n/.test(template);
 }
 
+/**
+ * properly adjusts template offsets based on current nesting levels
+ */
 export function reduceNestingOffset(
     el: ElementToMigrate, nestLevel: number, offset: number, postOffsets: number[]): number {
   if (el.nestCount <= nestLevel) {
@@ -178,6 +190,9 @@ function wrapIntoI18nContainer(i18nAttr: Attribute, content: string) {
   return `<ng-container ${i18n}>${content}</ng-container>`;
 }
 
+/**
+ * Counts, replaces, and removes any necessary ng-templates post control flow migration
+ */
 export function processNgTemplates(template: string): string {
   // count usage
   const templates = countTemplateUsage(template);
@@ -201,6 +216,10 @@ export function processNgTemplates(template: string): string {
   return template;
 }
 
+/**
+ * retrieves the original block of text in the template for length comparison during migration
+ * processing
+ */
 export function getOriginals(
     etm: ElementToMigrate, tmpl: string, offset: number): {start: string, end: string} {
   // original opening block
@@ -221,6 +240,9 @@ export function getOriginals(
   return {start, end: ''};
 }
 
+/**
+ * builds the proper contents of what goes inside a given control flow block after migration
+ */
 export function getMainBlock(etm: ElementToMigrate, tmpl: string, offset: number):
     {start: string, middle: string, end: string} {
   const i18nAttr = etm.el.attrs.find(x => x.name === 'i18n');