From 0709ed4c2be3a9673e961c569644f2cc8d330598 Mon Sep 17 00:00:00 2001
From: Judy Bogart <jbogart@gmail.com>
Date: Wed, 24 Jul 2019 12:58:42 -0700
Subject: [PATCH] docs: add doc for compiler options (#31829)

PR Close #31829
---
 aio/content/guide/angular-compiler-options.md | 148 +++++++++++++
 aio/content/guide/aot-compiler.md             | 203 +-----------------
 aio/content/guide/deprecations.md             |   2 +-
 aio/content/navigation.json                   |   5 +
 4 files changed, 157 insertions(+), 201 deletions(-)
 create mode 100644 aio/content/guide/angular-compiler-options.md

diff --git a/aio/content/guide/angular-compiler-options.md b/aio/content/guide/angular-compiler-options.md
new file mode 100644
index 0000000000..6775254bd8
--- /dev/null
+++ b/aio/content/guide/angular-compiler-options.md
@@ -0,0 +1,148 @@
+# Angular compiler options
+
+When you use [AOT compilation](guide/aot-compiler), you can control how your application is compiled by specifying *template* compiler options in the `tsconfig.json` [TypeScript configuration file](guide/typescript-configuration).
+
+The template options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler.
+
+```json
+    {
+      "compilerOptions": {
+        "experimentalDecorators": true,
+                  ...
+      },
+      "angularCompilerOptions": {
+        "fullTemplateTypeCheck": true,
+        "preserveWhitespaces": true,
+                  ...
+      }
+  }
+  ```
+This page describes the available Angular template compiler options.
+
+### `allowEmptyCodegenFiles`
+
+When true, generate all possible files even if they are empty. Default is false. Used by the Bazel build rules to simplify how Bazel rules track file dependencies. Do not use this option outside of the Bazel rules.
+
+### `annotationsAs`
+
+Modifies how Angular-specific annotations are emitted to improve tree-shaking. Non-Angular annotations are not affected. One of `static fields` (the default) or `decorators`.
+
+* By default, the compiler replaces decorators with a static field in the class, which allows advanced tree-shakers like [Closure compiler](https://github.com/google/closure-compiler) to remove unused classes.
+
+* The `decorators` value leaves the decorators in place, which makes compilation faster. TypeScript emits calls to the` __decorate` helper. Use `--emitDecoratorMetadata` for runtime reflection (but note taht the resulting code will not properly tree-shake.
+
+### `annotateForClosureCompiler`
+
+When true, use [Tsickle](https://github.com/angular/tsickle) to annotate the emitted JavaScript with [JSDoc](http://usejsdoc.org/) comments needed by the
+[Closure Compiler](https://github.com/google/closure-compiler). Default is false.
+
+### `disableExpressionLowering`
+
+When true (the default), transforms code that is or could be used in an annotation, to allow it to be imported from template factory modules. See [metadata rewriting](guide/aot-compiler#metadata-rewriting) for more information.
+
+When `false`, disables this rewriting, requiring the rewriting to be done manually.
+
+### `disableTypeScriptVersionCheck`
+
+When `true`, the compiler does not check the TypeScript version and does not report an error when an unsupported version of TypeScript is used. Not recommended, as unsupported versions of TypeScript might have undefined behavior. Default is false.
+
+### `enableResourceInlining`
+
+When true, replaces the `templateUrl` and `styleUrls` property in all `@Component` decorators with inlined contents in `template` and `styles` properties.
+
+When enabled, the `.js` output of `ngc` does not include any lazy-loaded template or style URLs.
+
+
+{@a enablelegacytemplate}
+
+### `enableLegacyTemplate`
+
+When true, enables use of the `<template>` element, which was deprecated in Angular 4.0, in favor of `<ng-template>` (to avoid colliding with the DOM's element of the same name). Default is false. Might be required by some third-party Angular libraries. |
+
+### `flatModuleId`
+
+The module ID to use for importing a flat module (when `flatModuleOutFile` is true). References generated by the template compiler use this module name when importing symbols
+from the flat module. Ignored if `flatModuleOutFile` is false.
+
+### `flatModuleOutFile`
+
+When true, generates a flat module index of the given file name and the corresponding flat module metadata. Use to create flat modules that are packaged similarly to `@angular/core` and `@angular/common`. When this option is used, the `package.json` for the library should refer
+to the generated flat module index instead of the library index file.
+
+Produces only one `.metadata.json` file, which contains all the metadata necessary
+for symbols exported from the library index. In the generated `.ngfactory.js` files, the flat
+module index is used to import symbols that includes both the public API from the library index
+as well as shrowded internal symbols.
+
+By default the `.ts` file supplied in the `files` field is assumed to be the library index.
+If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
+If more than one `.ts` file is supplied without a `libraryIndex`, an error is produced.
+
+A flat module index `.d.ts` and `.js` is created with the given `flatModuleOutFile` name in the same location as the library index `.d.ts` file.
+
+For example, if a library uses the `public_api.ts` file as the library index of the module, the `tsconfig.json` `files` field would be `["public_api.ts"]`.
+The `flatModuleOutFile` options could then be set to (for example) `"index.js"`, which produces `index.d.ts` and  `index.metadata.json` files.
+The `module` field of the library's `package.json` would be `"index.js"` and the `typings` field
+would be `"index.d.ts"`.
+
+### `fullTemplateTypeCheck`
+
+When true (recommended), enables the [binding expression validation](guide/aot-compiler#binding-expression-validation) phase of the template compiler, which uses TypeScript to validate binding expressions.
+
+Default is currently false.
+
+### `generateCodeForLibraries`
+
+When true (the default), generates factory files (`.ngfactory.js` and `.ngstyle.js`)
+for `.d.ts` files with a corresponding `.metadata.json` file.
+
+When false, factory files are generated only for `.ts` files. Do this when using factory summaries.
+
+
+### `preserveWhitespaces`
+
+When false (the default), removes blank text nodes from compiled templates, which results in smaller emitted template factory modules. Set to true to preserve blank text nodes.
+
+### `skipMetadataEmit`
+
+When true, does not to produce `.metadata.json` files. Default is `false`.
+
+The `.metadata.json` files contain information needed by the template compiler from a `.ts`
+file that is not included in the `.d.ts` file produced by the TypeScript compiler.
+This information includes, for example, the content of annotations  (such as a component's template), which TypeScript emits to the `.js` file but not to the `.d.ts` file.
+
+You can set to `true` when using factory summaries, because the factory summaries
+include a copy of the information that is in the `.metadata.json` file.
+
+Set to `true` if you are using TypeScript's `--outFile` option, because the metadata files
+are not valid for this style of TypeScript output. However, we do not recommend using `--outFile` with Angular. Use a bundler, such as [webpack](https://webpack.js.org/), instead.
+
+### `skipTemplateCodegen`
+
+When true, does not emit `.ngfactory.js` and `.ngstyle.js` files. This turns off most of the template compiler and disables the reporting of template diagnostics.
+
+Can be used to instruct the template compiler to produce `.metadata.json` files for distribution with an `npm` package while avoiding the production of `.ngfactory.js` and `.ngstyle.js` files that cannot be distributed to `npm`.
+
+### `strictMetadataEmit`
+
+When true, reports an error to the `.metadata.json` file if `"skipMetadataEmit"` is `false`.
+Default is false. Use only when `"skipMetadataEmit"` is false and `"skipTemplateCodeGen"` is true.
+
+This option is intended to validate the `.metadata.json` files emitted for bundling with an `npm` package. The validation is strict and can emit errors for metadata that would never produce an error when used by the template compiler. You can choose to suppress the error emitted by this option for an exported symbol by including `@dynamic` in the comment documenting the symbol.
+
+It is valid for `.metadata.json` files to contain errors.
+The template compiler reports these errors if the metadata is used to determine the contents of an annotation.
+The metadata collector cannot predict the symbols that are designed for use in an annotation, so it preemptively includes error nodes in the metadata for the exported symbols.
+The template compiler can then use the error nodes to report an error if these symbols are used.
+
+If the client of a library intends to use a symbol in an annotation, the template compiler does not normally report this until the client uses the symbol.
+This option allows detection of these errors during the build phase of
+the library and is used, for example, in producing Angular libraries themselves.
+
+### `strictInjectionParameters`
+
+When true (recommended), reports an error for a supplied parameter whose injection type cannot be determined. When false (currently the default), constructor parameters of classes marked with `@Injectable` whose type cannot be resolved produce a warning.
+
+### `trace`
+
+When true, prints extra information while compiling templates. Default is false.
diff --git a/aio/content/guide/aot-compiler.md b/aio/content/guide/aot-compiler.md
index ce2be6ef1b..5ad583d0fc 100644
--- a/aio/content/guide/aot-compiler.md
+++ b/aio/content/guide/aot-compiler.md
@@ -79,11 +79,9 @@ there are fewer opportunities for injection attacks.
 
 When you use the Angular AOT compiler, you can control your app compilation in two ways:
 
-* By providing template compiler options in the `tsconfig.json` file.
+* By [specifying Angular metadata](#metadata-aot), as described below.
 
-      For more information, see [Angular template compiler options](#compiler-options).
-
-* By [specifying Angular metadata](#metadata-aot).
+* By providing options in the `tsconfig.json` [TypeScript configuration file](guide/typescript-configuration). See [Angular compiler options](guide/angular-compiler-options).
 
 
 {@a metadata-aot}
@@ -1165,7 +1163,7 @@ Chuck: After reviewing your PR comment I'm still at a loss. See [comment there](
   In the validation phase, the Angular template compiler uses the TypeScript compiler to validate the
   binding expressions in templates. Enable this phase explicitly by adding the compiler
   option `"fullTemplateTypeCheck"` in the `"angularCompilerOptions"` of the project's `tsconfig.json` (see
-  [Angular Compiler Options](#compiler-options)).
+  [Angular Compiler Options](guide/angular-compiler-options)).
 
   Template validation produces error messages when a type error is detected in a template binding
   expression, similar to how type errors are reported by the TypeScript compiler against code in a `.ts`
@@ -1329,198 +1327,3 @@ Similar to TypeScript Compiler, Angular Compiler also supports `extends` in the
 }
 ```
  More information about tsconfig extends can be found in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
-
-{@a compiler-options}
-## Angular template compiler options
-
-The template compiler options are specified as members of the `"angularCompilerOptions"` object in the `tsconfig.json` file. Specify template compiler options along with the options supplied to the TypeScript compiler as shown here:
-
-    ```json
-    {
-      "compilerOptions": {
-        "experimentalDecorators": true,
-                  ...
-      },
-      "angularCompilerOptions": {
-        "fullTemplateTypeCheck": true,
-        "preserveWhitespaces": true,
-                  ...
-      }
-  }
-  ```
-
-The following section describes the Angular's template compiler options.
-
-### *enableResourceInlining*
-This option instructs the compiler to replace the `templateUrl` and `styleUrls` property in all `@Component` decorators with inlined contents in `template` and `styles` properties.
-When enabled, the `.js` output of `ngc` will have no lazy-loaded `templateUrl` or `styleUrls`.
-
-### *skipMetadataEmit*
-
-This option tells the compiler not to produce `.metadata.json` files.
-The option is `false` by default.
-
-`.metadata.json` files contain information needed by the template compiler from a `.ts`
-file that is not included in the `.d.ts` file produced by the TypeScript compiler. This information contains,
-for example, the content of annotations (such as a component's template), which TypeScript
-emits to the `.js` file but not to the `.d.ts` file.
-
-This option should be set to `true` if you are using TypeScript's `--outFile` option, because the metadata files
-are not valid for this style of TypeScript output. It is not recommended to use `--outFile` with
-Angular. Use a bundler, such as [webpack](https://webpack.js.org/), instead.
-
-This option can also be set to `true` when using factory summaries because the factory summaries
-include a copy of the information that is in the `.metadata.json` file.
-
-### *strictMetadataEmit*
-
-This option tells the template compiler to report an error to the `.metadata.json`
-file if `"skipMetadataEmit"` is `false`. This option is `false` by default. This should only be used when `"skipMetadataEmit"` is `false` and `"skipTemplateCodeGen"` is `true`.
-
-This option is intended to validate the `.metadata.json` files emitted for bundling with an `npm` package. The validation is strict and can emit errors for metadata that would never produce an error when used by the template compiler. You can choose to suppress the error emitted by this option for an exported symbol by including `@dynamic` in the comment documenting the symbol.
-
-It is valid for `.metadata.json` files to contain errors. The template compiler reports these errors
-if the metadata is used to determine the contents of an annotation. The metadata
-collector cannot predict the symbols that are designed for use in an annotation, so it will preemptively
-include error nodes in the metadata for the exported symbols. The template compiler can then use the error
-nodes to report an error if these symbols are used. If the client of a library intends to use a symbol in an annotation, the template compiler will not normally report
-this until the client uses the symbol. This option allows detecting these errors during the build phase of
-the library and is used, for example, in producing Angular libraries themselves.
-
-### *skipTemplateCodegen*
-
-This option tells the compiler to suppress emitting `.ngfactory.js` and `.ngstyle.js` files. When set,
-this turns off most of the template compiler and disables reporting template diagnostics.
-This option can be used to instruct the
-template compiler to produce `.metadata.json` files for distribution with an `npm` package while
-avoiding the production of `.ngfactory.js` and `.ngstyle.js` files that cannot be distributed to
-`npm`.
-
-### *strictInjectionParameters*
-
-When set to `true`, this options tells the compiler to report an error for a parameter supplied
-whose injection type cannot be determined. When this option is not provided or is `false`, constructor parameters of classes marked with `@Injectable` whose type cannot be resolved will
-produce a warning.
-
-*Note*: It is recommended to change this option explicitly to `true` as this option will default to `true` in the future.
-
-### *flatModuleOutFile*
-
-When set to `true`, this option tells the template compiler to generate a flat module
-index of the given file name and the corresponding flat module metadata. Use this option when creating
-flat modules that are packaged similarly to `@angular/core` and `@angular/common`. When this option
-is used, the `package.json` for the library should refer
-to the generated flat module index instead of the library index file. With this
-option only one `.metadata.json` file is produced, which contains all the metadata necessary
-for symbols exported from the library index. In the generated `.ngfactory.js` files, the flat
-module index is used to import symbols that includes both the public API from the library index
-as well as shrowded internal symbols.
-
-By default the `.ts` file supplied in the `files` field is assumed to be the library index.
-If more than one `.ts` file is specified, `libraryIndex` is used to select the file to use.
-If more than one `.ts` file is supplied without a `libraryIndex`, an error is produced. A flat module
-index `.d.ts` and `.js` will be created with the given `flatModuleOutFile` name in the same
-location as the library index `.d.ts` file. For example, if a library uses the
-`public_api.ts` file as the library index of the module, the `tsconfig.json` `files` field
-would be `["public_api.ts"]`. The `flatModuleOutFile` options could then be set to, for
-example `"index.js"`, which produces `index.d.ts` and  `index.metadata.json` files. The
-library's `package.json`'s `module` field would be `"index.js"` and the `typings` field
-would be `"index.d.ts"`.
-
-### *flatModuleId*
-
-This option specifies the preferred module id to use for importing a flat module.
-References generated by the template compiler will use this module name when importing symbols
-from the flat module.
-This is only meaningful when `flatModuleOutFile` is also supplied. Otherwise the compiler ignores
-this option.
-
-### *generateCodeForLibraries*
-
-This option tells the template compiler to generate factory files (`.ngfactory.js` and `.ngstyle.js`)
-for `.d.ts` files with a corresponding `.metadata.json` file. This option defaults to
-`true`. When this option is `false`, factory files are generated only for `.ts` files.
-
-This option should be set to `false` when using factory summaries.
-
-### *fullTemplateTypeCheck*
-
-This option tells the compiler to enable the [binding expression validation](#binding-expression-validation)
-phase of the template compiler which uses TypeScript to validate binding expressions.
-
-This option is `false` by default.
-
-*Note*: It is recommended to set this to `true` because this option will default to `true` in the future.
-
-### *annotateForClosureCompiler*
-
-This option tells the compiler to use [Tsickle](https://github.com/angular/tsickle) to annotate the emitted
-JavaScript with [JSDoc](http://usejsdoc.org/) comments needed by the
-[Closure Compiler](https://github.com/google/closure-compiler). This option defaults to `false`.
-
-### *annotationsAs*
-
-Use this option to modify how the Angular specific annotations are emitted to improve tree-shaking. Non-Angular
-annotations and decorators are unaffected. Default is `static fields`.
-
-<style>
-  td, th {vertical-align: top}
-</style>
-
-<table>
-  <tr>
-    <th>Value</th>
-    <th>Description</th>
-  </tr>
-  <tr>
-    <td><code>decorators</code></td>
-    <td>Leave the decorators in place. This makes compilation faster. TypeScript will emit calls to the __decorate helper.  Use <code>--emitDecoratorMetadata</code> for runtime reflection.  However, the resulting code will not properly tree-shake.</td>
-  </tr>
-  <tr>
-    <td><code>static fields</code></td>
-    <td>Replace decorators with a static field in the class. Allows advanced tree-shakers like
-    <a href="https://github.com/google/closure-compiler">Closure compiler</a> to remove unused classes.</td>
-  </tr>
-  </table>
-
-
-### *trace*
-
-This tells the compiler to print extra information while compiling templates.
-
-### *enableLegacyTemplate*
-
-Use of  the `<template>` element was deprecated starting in Angular 4.0 in favor of using
-`<ng-template>` to avoid colliding with the DOM's element of the same name. Setting this option to
-`true` enables the use of the deprecated `<template>` element. This option
-is `false` by default. This option might be required by some third-party Angular libraries.
-
-### *disableExpressionLowering*
-
-The Angular template compiler transforms code that is used, or could be used, in an annotation
-to allow it to be imported from template factory modules. See
-[metadata rewriting](#metadata-rewriting) for more information.
-
-Setting this option to `false` disables this rewriting, requiring the rewriting to be
-done manually.
-
-### *disableTypeScriptVersionCheck*
-
-When `true`, this option tells the compiler not to check the TypeScript version.
-The compiler will skip checking and will not error out when an unsupported version of TypeScript is used.
-Setting this option to `true` is not recommended because unsupported versions of TypeScript might have undefined behavior.
-
-This option is `false` by default.
-
-### *preserveWhitespaces*
-
-This option tells the compiler whether to remove blank text nodes from compiled templates.
-As of v6, this option is `false` by default, which results in smaller emitted template factory modules.
-
-### *allowEmptyCodegenFiles*
-
-Tells the compiler to generate all the possible generated files even if they are empty. This option is
-`false` by default. This is an option used by the Bazel build rules and is needed to simplify
-how Bazel rules track file dependencies. It is not recommended to use this option outside of the Bazel
-rules.
-
diff --git a/aio/content/guide/deprecations.md b/aio/content/guide/deprecations.md
index 664d3de564..720c42a674 100644
--- a/aio/content/guide/deprecations.md
+++ b/aio/content/guide/deprecations.md
@@ -178,7 +178,7 @@ For more information, see [/deep/, >>>, and ::ng-deep](guide/component-styles#de
 {@a template-tag}
 ### &lt;template&gt; tag
 
-The `<template>` tag was deprecated in v4 to avoid colliding with the DOM's element of the same name (such as when using web components). Use `<ng-template>` instead. For more information, see the [Ahead-of-Time Compilation](guide/aot-compiler#enablelegacytemplate) guide.
+The `<template>` tag was deprecated in v4 to avoid colliding with the DOM's element of the same name (such as when using web components). Use `<ng-template>` instead. For more information, see the [Ahead-of-Time Compilation](guide/angular-compiler-options#enablelegacytemplate) guide.
 
 
 
diff --git a/aio/content/navigation.json b/aio/content/navigation.json
index e3618c95a1..d1c986c501 100644
--- a/aio/content/navigation.json
+++ b/aio/content/navigation.json
@@ -597,6 +597,11 @@
           "title": "Ahead-of-Time Compilation",
           "tooltip": "Learn why and how to use the Ahead-of-Time (AOT) compiler."
         },
+        {
+          "url": "guide/angular-compiler-options",
+          "title": "Compiler Options",
+          "tooltip": "Configuration options for the AOT compiler."
+        },
         {
           "url": "guide/build",
           "title": "Building & Serving",