Skip to content

Commit

Permalink
docs: apply standard header case convention (angular#34196)
Browse files Browse the repository at this point in the history
PR Close angular#34196
  • Loading branch information
jbogarthyde authored and atscott committed Jan 10, 2020
1 parent 9e05830 commit efdf347
Show file tree
Hide file tree
Showing 56 changed files with 188 additions and 173 deletions.
3 changes: 1 addition & 2 deletions aio/content/guide/ajs-quick-reference.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AngularJS to Angular Concepts: Quick Reference
# AngularJS to Angular concepts: Quick reference


{@a top}
Expand Down Expand Up @@ -1271,4 +1271,3 @@ also encapsulate a style sheet within a specific component.
</tr>

</table>

4 changes: 2 additions & 2 deletions aio/content/guide/aot-compiler.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# The Ahead-of-Time (AOT) compiler
# Ahead-of-time (AOT) compilation

An Angular application consists mainly of components and their HTML templates. Because the components and templates provided by Angular cannot be understood by the browser directly, Angular applications require a compilation process before they can run in a browser.

The Angular Ahead-of-Time (AOT) compiler converts your Angular HTML and TypeScript code into efficient JavaScript code during the build phase _before_ the browser downloads and runs that code. Compiling your application during the build process provides a faster rendering in the browser.
The Angular [ahead-of-time (AOT) compiler](guide/glossary#aot) converts your Angular HTML and TypeScript code into efficient JavaScript code during the build phase _before_ the browser downloads and runs that code. Compiling your application during the build process provides a faster rendering in the browser.

This guide explains how to specify metadata and apply available compiler options to compile your applications efficiently using the AOT compiler.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/aot-metadata-errors.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AoT metadata errors
# AOT metadata errors

The following are metadata errors you may encounter, with explanations and suggested corrections.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/attribute-directives.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Attribute Directives
# Attribute directives

An **Attribute** directive changes the appearance or behavior of a DOM element.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/cli-builder.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Angular CLI Builders
# Angular CLI builders

A number of Angular CLI commands run a complex process on your code, such as linting, building, or testing.
The commands use an internal tool called Architect to run *CLI builders*, which apply another tool to accomplish the desired task.
Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/component-interaction.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Component Interaction
# Component interaction

{@a top}

Expand Down
4 changes: 2 additions & 2 deletions aio/content/guide/component-styles.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Component Styles
# Component styles

Angular applications are styled with standard CSS. That means you can apply
everything you know about CSS stylesheets, selectors, rules, and media queries
Expand Down Expand Up @@ -289,7 +289,7 @@ Choose from the following modes:

* `Emulated` view encapsulation (the default) emulates the behavior of shadow DOM by preprocessing
(and renaming) the CSS code to effectively scope the CSS to the component's view.
For details, see [Appendix 1](guide/component-styles#inspect-generated-css).
For details, see [Inspecting generated CSS](guide/component-styles#inspect-generated-css) below.

* `None` means that Angular does no view encapsulation.
Angular adds the CSS to the global styles.
Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/creating-libraries.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Creating Libraries
# Creating libraries

You can create and publish new libraries to extend Angular functionality. If you find that you need to solve the same problem in more than one app (or want to share your solution with other developers), you have a candidate for a library.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/dependency-injection-in-action.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Dependency Injection in Action
# Dependency injection in action

This section explores many of the features of dependency injection (DI) in Angular.
{@a toc}
Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/dependency-injection-providers.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Dependency Providers
# Dependency providers

A dependency [provider](guide/glossary#provider) configures an injector
with a [DI token](guide/glossary#di-token),
Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/dependency-injection.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Dependency Injection in Angular
# Dependency injection in Angular

Dependency injection (DI), is an important application design pattern.
Angular has its own DI framework, which is typically
Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/deprecations.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Deprecated APIs and Features
# Deprecated APIs and features

Angular strives to balance innovation and stability.
Sometimes, APIs and features become obsolete and need to be removed or replaced so that Angular can stay current with new best practices, changing dependencies, or changes in the (web) platform itself.
Expand Down
3 changes: 1 addition & 2 deletions aio/content/guide/displaying-data.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Displaying Data
# Displaying data

You can display data by binding controls in an HTML template to properties of an Angular component.

Expand Down Expand Up @@ -361,4 +361,3 @@ Here's the final code:
</code-pane>

</code-tabs>

14 changes: 8 additions & 6 deletions aio/content/guide/docs-style-guide.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Angular Documentation Style Guide
# Angular documentation style guide
<!-- formerly Authors Style Guide -->

This Style Guide is for anyone who contributes to the Angular documentation (this site).
This style guide is for anyone who contributes to the Angular documentation (this site).
These guidelines should be followed by all authors.
Deviations must be approved by a documentation editor.

Expand Down Expand Up @@ -139,24 +139,26 @@ The title should appear at the top of the physical page.
Begin the title with the markdown `#` character. Alternatively, you can write the equivalent `<h1>`.

```html
# Authors Style Guide
# Angular documentation style guide
```

**Only one title (`<h1>`) per document!**

Title text should be in "Title Case", which means that you use capital letters to start the first words and all _principal_ words. Use lower case letters for _secondary_ words such as "in", "of", and "the".
Title text should be in "Sentence case", which means the first word is capitalized and all other words are lower case (unless they are technical terms that are always capitalized, like "Angular").

```html
# The Meat of the Matter
# Deprecation policy in Angular
```

**Always follow the title with at least one blank line.**

Note that the corresponding left-nav TOC text should be in "title case", which means that you use capital letters to start the first words and all principal words. Use lower case letters for secondary words such as "in", "of", and "the". The TOC title can also be shortened to fit in the column.

## Sections

A typical document is divided into sections.

All section heading text should be in "Sentence case", which means the first word is capitalized and all other words are lower case.
All heading text should be in "Sentence case", which means the first word is capitalized and all other words are lower case.

**Always follow the section heading with at least one blank line.**

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/dynamic-component-loader.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Dynamic Component Loader
# Dynamic component loader

Component templates are not always fixed. An application may need to load new components at runtime.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/dynamic-form.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Dynamic Forms
# Dynamic forms

{@a top}

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/elements.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Angular Elements Overview
# Angular elements overview

_Angular elements_ are Angular components packaged as _custom elements_ (also called Web Components), a web standard for defining new HTML elements in a framework-agnostic way.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/entry-components.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Entry Components
# Entry components

An entry component is any component that Angular loads imperatively, (which means you’re not referencing it in the template), by type. You specify an entry component by bootstrapping it in an NgModule, or including it in a routing definition.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/feature-modules.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Feature Modules
# Feature modules

Feature modules are NgModules for the purpose of organizing code.

Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/form-validation.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Form Validation
# Form validation



Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/frequent-ngmodules.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Frequently Used Modules
# Frequently-used modules

An Angular app needs at least one module that serves as the root module.
As you add features to your app, you can add them in modules.
Expand Down
24 changes: 24 additions & 0 deletions aio/content/guide/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -478,6 +478,15 @@ or displayed between element tags, as in this example.

Read more about [interpolation](guide/template-syntax#interpolation) in [Template Syntax](guide/template-syntax).

{@a ivy}

## Ivy

Ivy is the code name for Angular's [next-generation compilation and rendering pipeline](https://blog.angular.io/a-plan-for-version-8-0-and-ivy-b3318dfc19f7).
With the version 9 release of Angular, the new compiler and runtime instructions are used by default instead of the older compiler and runtime, known as [View Engine](#ve).

See [Angular Ivy](guide/ivy).


{@a J}

Expand Down Expand Up @@ -572,6 +581,14 @@ Compare to [NgModule](#ngmodule).

{@a N}

{@a ngcc}

## ngcc (Angular Compatability Compiler)

The CLI automatically runs the `ngcc` process to compile all your libraries with [Ivy](#ivy).
If your app uses Ivy, but depends on libraries that don't use Ivy, `ngcc` automatically updates the dependent libraries to use Ivy when you compile your app.


{@a ngmodule}

## NgModule
Expand Down Expand Up @@ -951,6 +968,13 @@ You can change the structure of elements by inserting, moving, or removing neste

View hierarchies can be loaded and unloaded dynamically as the user navigates through the application, typically under the control of a [router](#router).

{@a ve}

## View Engine

The compilation and rendering pipeline used by Angular before version 9. Compare [Ivy](#ivy).


{@a view-tree}

## view hierarchy
Expand Down
52 changes: 26 additions & 26 deletions aio/content/guide/ivy-compatibility-examples.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Appendix: Ivy Compatibility Examples
# Ivy compatibility examples

This appendix is intended to provide more background on Ivy changes. Many of these examples list error messages you may see, so searching by error message might be a good idea if you are debugging.

Expand All @@ -8,10 +8,10 @@ NOTE: Most of these issues affect a small percentage of applications encounterin


{@a content-children-descendants}
## @ContentChildren Queries Only Match Direct Children By Default
## @ContentChildren queries only match direct children by default


### Basic example of change
### Basic example of change

Let's say a component (`Comp`) has a `@ContentChildren` query for `'foo'`:

Expand All @@ -23,15 +23,15 @@ Let's say a component (`Comp`) has a `@ContentChildren` query for `'foo'`:
</comp>
```

In the previous runtime, the `<div>` with `#foo` would match.
In the previous runtime, the `<div>` with `#foo` would match.
With Ivy, that `<div>` does not match because it is not a direct child of `<comp>`.


### Background

By default, `@ContentChildren` queries have the `descendants` flag set to `false`.
By default, `@ContentChildren` queries have the `descendants` flag set to `false`.

In the previous rendering engine, "descendants" referred to "descendant directives".
In the previous rendering engine, "descendants" referred to "descendant directives".
An element could be a match as long as there were no other directives between the element and the requesting directive.
This made sense for directives with nesting like tabs, where nested tab directives might not be desirable to match.
However, this caused surprising behavior for users because adding an unrelated directive like `ngClass` to a wrapper element could invalidate query results.
Expand All @@ -49,7 +49,7 @@ For example, with the content query and template below, the last two `Tab` direc
</div>
<tab> <!-- match (top level) -->
<tab> A </tab> <!-- not a match (nested in tab) -->
</tab>
</tab>
<div [ngClass]="classes">
<tab> Two </tab> <!-- not a match (nested in ngClass) -->
</div>
Expand All @@ -70,15 +70,15 @@ For example, if you replace the type predicate above with a `'foo'` string predi
</div>
<tab #foo> <!-- match (top level) -->
<div #foo> A </div> <!-- match (nested in tab) -->
</tab>
</tab>
<div [ngClass]="classes">
<div #foo> Two </div> <!-- match (nested in ngClass) -->
</div>
</tab-list>
```

Because the previous behavior was inconsistent and surprising to users, we did not want to reproduce it in Ivy.
Instead, we simplified the mental model so that "descendants" refers to DOM nesting only.
Instead, we simplified the mental model so that "descendants" refers to DOM nesting only.
Any DOM element between the requesting component and a potential match will invalidate that match.
Type predicates and string predicates also have identical matching behavior.

Expand All @@ -90,7 +90,7 @@ Ivy behavior for directive/string predicates:
</div>
<tab> <!-- match (top level) -->
<tab> A </tab> <!-- not a match (nested in tab) -->
</tab>
</tab>
<div [ngClass]="classes">
<tab> Two </tab> <!-- not a match (nested in div) -->
</div>
Expand All @@ -101,38 +101,38 @@ Ivy behavior for directive/string predicates:
### Example of error

The error message that you see will depend on how the particular content query is used in the application code.
Frequently, an error is thrown when a property is referenced on the content query result (which is now `undefined`).
Frequently, an error is thrown when a property is referenced on the content query result (which is now `undefined`).

For example, if the component sets the content query results to a property, `foos`, `foos.first.bar` would throw the error:

```
Uncaught TypeError: Cannot read property 'bar' of undefined
```

If you see an error like this, and the `undefined` property refers to the result of a `@ContentChildren` query, it may well be caused by this change.
If you see an error like this, and the `undefined` property refers to the result of a `@ContentChildren` query, it may well be caused by this change.


### Recommended fix

You can either add the `descendants: true` flag to ignore wrapper elements or remove the wrapper elements themselves.

Option 1:
Option 1:
```
@ContentChildren('foo', {descendants: true}) foos: QueryList<ElementRef>;
```

Option 2:
Option 2:
```
<comp>
<div #foo></div> <!-- matches in both old runtime and new runtime -->
</comp>
```

{@a undecorated-classes}
## All Classes That Use Angular DI Must Have An Angular Class-level Decorator
## All classes that use Angular DI must have an Angular class-level decorator


### Basic example of change:
### Basic example of change:

In the previous rendering engine, the following would work:

Expand Down Expand Up @@ -165,13 +165,13 @@ However, as you're adding new code in version 9, you may run into this differenc

### Background

When a class has an Angular decorator like `@Injectable` or `@Directive`, the Angular compiler generates extra code to support injecting dependencies into the constructor of your class.
When using inheritance, Ivy needs both the parent class and the child class to apply a decorator to generate the correct code.
When a class has an Angular decorator like `@Injectable` or `@Directive`, the Angular compiler generates extra code to support injecting dependencies into the constructor of your class.
When using inheritance, Ivy needs both the parent class and the child class to apply a decorator to generate the correct code.
Otherwise, when the decorator is missing from the parent class, the subclass will inherit a constructor from a class for which the compiler did not generate special constructor info, and Angular won't have the dependency info it needs to create it properly.

In the previous rendering engine, the compiler had global knowledge, so in some cases (such as AOT mode or the presence of certain injection flags), it could look up the missing data.
However, the Ivy compiler only processes each class in isolation.
This means that compilation has the potential to be faster (and opens the framework up for optimizations and features going forward), but the compiler can't automatically infer the same information as before.
In the previous rendering engine, the compiler had global knowledge, so in some cases (such as AOT mode or the presence of certain injection flags), it could look up the missing data.
However, the Ivy compiler only processes each class in isolation.
This means that compilation has the potential to be faster (and opens the framework up for optimizations and features going forward), but the compiler can't automatically infer the same information as before.

Adding the proper decorator explicitly provides this information.

Expand All @@ -180,7 +180,7 @@ Adding the proper decorator explicitly provides this information.
In JIT mode, the framework will throw the following error:

```
ERROR: This constructor is not compatible with Angular Dependency Injection because its dependency at index X of the parameter list is invalid.
ERROR: This constructor is not compatible with Angular Dependency Injection because its dependency at index X of the parameter list is invalid.
This can happen if the dependency type is a primitive like a string or if an ancestor of this class is missing an Angular decorator.
Please check that 1) the type for the parameter at index X is correct and 2) the correct Angular decorators are defined for this class and its ancestors.
Expand All @@ -189,14 +189,14 @@ Please check that 1) the type for the parameter at index X is correct and 2) the
In AOT mode, you'll see something like:

```
X inherits its constructor from Y, but the latter does not have an Angular decorator of its own.
Dependency injection will not be able to resolve the parameters of Y's constructor. Either add a
X inherits its constructor from Y, but the latter does not have an Angular decorator of its own.
Dependency injection will not be able to resolve the parameters of Y's constructor. Either add a
@Directive decorator to Y, or add an explicit constructor to X.
```

In some cases, the framework may not be able to detect the missing decorator.
In some cases, the framework may not be able to detect the missing decorator.
In these cases, you'll generally see a runtime error thrown when there is a property access attempted on the missing dependency.
If dependency was `foo`, you'd see an error when accessing something like `foo.bar`:
If dependency was `foo`, you'd see an error when accessing something like `foo.bar`:

```
Uncaught TypeError: Cannot read property 'bar' of undefined
Expand Down
Loading

0 comments on commit efdf347

Please sign in to comment.