docs(core): improve viewEncapsulation documentation (#44151)

Slighlty improve the `viewEncapsulation` documentation (both in code
comments and content files) to make it more clear and understandable.

See https://github.com/angular/angular/pull/44099#discussion_r745890903

PR Close #44151

packages/compiler/src/render3/partial/api.ts

@@ -177,7 +177,7 @@ export interface R3DeclareComponentMetadata extends R3DeclareDirectiveMetadata {
   changeDetection?: ChangeDetectionStrategy;
 
   /**
-   * An encapsulation policy for the template and CSS styles.
+   * An encapsulation policy for the component's styling.
    * Defaults to `ViewEncapsulation.Emulated`.
    */
   encapsulation?: ViewEncapsulation;

packages/compiler/src/render3/view/api.ts

@@ -206,11 +206,12 @@ export interface R3ComponentMetadata extends R3DirectiveMetadata {
   styles: string[];
 
   /**
-   * An encapsulation policy for the template and CSS styles. One of:
-   * - `ViewEncapsulation.Emulated`: Use shimmed CSS that emulates the native behavior.
-   * - `ViewEncapsulation.None`: Use global CSS without any encapsulation.
-   * - `ViewEncapsulation.ShadowDom`: Use the latest ShadowDOM API to natively encapsulate styles
-   * into a shadow root.
+   * An encapsulation policy for the component's styling.
+   * Possible values:
+   * - `ViewEncapsulation.Emulated`: Apply modified component styles in order to emulate
+   *                                 a native Shadow DOM CSS encapsulation behavior.
+   * - `ViewEncapsulation.None`: Apply component styles globally without any sort of encapsulation.
+   * - `ViewEncapsulation.ShadowDom`: Use the browser's native Shadow DOM API to encapsulate styles.
    */
   encapsulation: ViewEncapsulation;
 

packages/core/src/metadata/directives.ts

@@ -516,18 +516,19 @@ export interface Component extends Directive {
   animations?: any[];
 
   /**
-   * An encapsulation policy for the template and CSS styles. One of:
-   * - `ViewEncapsulation.Emulated`: Use shimmed CSS that
-   * emulates the native behavior.
-   * - `ViewEncapsulation.None`: Use global CSS without any
-   * encapsulation.
-   * - `ViewEncapsulation.ShadowDom`: Use Shadow DOM v1 to encapsulate styles.
+   * An encapsulation policy for the component's styling.
+   * Possible values:
+   * - `ViewEncapsulation.Emulated`: Apply modified component styles in order to emulate
+   *                                 a native Shadow DOM CSS encapsulation behavior.
+   * - `ViewEncapsulation.None`: Apply component styles globally without any sort of encapsulation.
+   * - `ViewEncapsulation.ShadowDom`: Use the browser's native Shadow DOM API to encapsulate styles.
    *
-   * If not supplied, the value is taken from `CompilerOptions`. The default compiler option is
-   * `ViewEncapsulation.Emulated`.
+   * If not supplied, the value is taken from the `CompilerOptions`
+   * which defaults to `ViewEncapsulation.Emulated`.
    *
-   * If the policy is set to `ViewEncapsulation.Emulated` and the component has no `styles`
-   * or `styleUrls` specified, the policy is automatically switched to `ViewEncapsulation.None`.
+   * If the policy is `ViewEncapsulation.Emulated` and the component has no
+   * {@link Component#styles styles} nor {@link Component#styleUrls styleUrls},
+   * the policy is automatically switched to `ViewEncapsulation.None`.
    */
   encapsulation?: ViewEncapsulation;
 

packages/core/src/metadata/view.ts

@@ -7,7 +7,8 @@
  */
 
 /**
- * Defines template and style encapsulation options available for Component's {@link Component}.
+ * Defines the CSS styles encapsulation policies for the {@link Component} decorator's
+ * `encapsulation` option.
  *
  * See {@link Component#encapsulation encapsulation}.
  *
@@ -23,10 +24,9 @@ export enum ViewEncapsulation {
   // https://github.com/angular/angular/issues/44119 for additional information.
 
   /**
-   * Emulate `Native` scoping of styles by adding an attribute containing surrogate id to the Host
-   * Element and pre-processing the style rules provided via {@link Component#styles styles} or
-   * {@link Component#styleUrls styleUrls}, and adding the new Host Element attribute to all
-   * selectors.
+   * Emulates a native Shadow DOM encapsulation behavior by adding a specific attribute to the
+   * component's host element and applying the same attribute to all the CSS selectors provided
+   * via {@link Component#styles styles} or {@link Component#styleUrls styleUrls}.
    *
    * This is the default option.
    */
@@ -35,16 +35,16 @@ export enum ViewEncapsulation {
   // Historically the 1 value was for `Native` encapsulation which has been removed as of v11.
 
   /**
-   * Don't provide any template or style encapsulation.
+   * Doesn't provide any sort of CSS style encapsulation, meaning that all the styles provided
+   * via {@link Component#styles styles} or {@link Component#styleUrls styleUrls} are applicable
+   * to any HTML element of the application regardless of their host Component.
    */
   None = 2,
 
   /**
-   * Use Shadow DOM to encapsulate styles.
-   *
-   * For the DOM this means using modern [Shadow
-   * DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) and
-   * creating a ShadowRoot for Component's Host Element.
+   * Uses the browser's native Shadow DOM API to encapsulate CSS styles, meaning that it creates
+   * a ShadowRoot for the component's host element which is then used to encapsulate
+   * all the Component's styling.
    */
   ShadowDom = 3
 }