cargdev/angular
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix invalid headings (#24000)

Browse Source 
PR Close #24000
This commit is contained in:
Pete Bacon Darwin
2018-05-18 16:13:00 +01:00
committed by Miško Hevery
parent 77309e2ea4
commit e6516b0229
26 changed files with 255 additions and 473 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
packages/core/src/metadata/di.ts
View File

@ -16,6 +16,7 @@ import {makeParamDecorator, makePropDecorator} from '../util/decorators';
* All components that are referenced in the `useValue` value (either directly
* or in a nested array or map) will be added to the `entryComponents` property.
*
* @usageNotes
* ### Example
* The following example shows how the router can populate the `entryComponents`
* field of an NgModule based on the router configuration which refers
@ -57,6 +58,7 @@ export interface AttributeDecorator {
*
* The directive can inject constant string literals of host element attributes.
*
* @usageNotes
* ### Example
*
* Suppose we have an `<input>` element and want to know its `type`.
@ -103,7 +105,6 @@ export interface Attribute { attributeName?: string; }
/**
* Attribute decorator and metadata.
*
*
* @Annotation
*/
export const Attribute: AttributeDecorator =
@ -111,8 +112,6 @@ export const Attribute: AttributeDecorator =
/**
* Type of the Query metadata.
*
*
*/
export interface Query {
descendants: boolean;
@ -125,34 +124,25 @@ export interface Query {
/**
* Base class for query metadata.
*
* See {@link ContentChildren}, {@link ContentChild}, {@link ViewChildren}, {@link ViewChild} for
* more information.
*
*
* @see `ContentChildren`.
* @see `ContentChild`.
* @see `ViewChildren`.
* @see `ViewChild`.
*/
export abstract class Query {}
/**
* Type of the ContentChildren decorator / constructor function.
*
* See {@link ContentChildren}.
*
*
* @see `ContentChildren`.
*/
export interface ContentChildrenDecorator {
/**
*
* @usageNotes
*
* {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'}
*
* @description
* Configures a content query.
*
* You can use ContentChildren to get the {@link QueryList} of elements or directives from the
* You can use ContentChildren to get the `QueryList` of elements or directives from the
* content DOM. Any time a child element is added, removed, or moved, the query list will be
* updated,
* and the changes observable of the query list will emit a new value.
* updated, and the changes observable of the query list will emit a new value.
*
* Content queries are set before the `ngAfterContentInit` callback is called.
*
@ -162,13 +152,20 @@ export interface ContentChildrenDecorator {
* * **descendants** - include only direct children or all descendants.
* * **read** - read a different token from the queried elements.
*
* Let's look at an example:
* @usageNotes
* ### Basic Example
*
* Here is a simple demonstration of how the `ContentChildren` decorator can be used.
*
* {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'}
*
* ### Tab-pane Example
*
* Here is a slightly more realistic example that shows how `ContentChildren` decorators
* can be used to implement a tab pane component.
*
* {@example core/di/ts/contentChildren/content_children_example.ts region='Component'}
*
* **npm package**: `@angular/core`
*
*
* @Annotation
*/
(selector: Type<any>|Function|string, opts?: {descendants?: boolean, read?: any}): any;
@ -203,12 +200,6 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator(
*/
export interface ContentChildDecorator {
/**
*
* @usageNotes
*
* {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'}
*
* @description
* Configures a content query.
*
* You can use ContentChild to get the first element or the directive matching the selector from
@ -222,13 +213,15 @@ export interface ContentChildDecorator {
* * **selector** - the directive type or the name used for querying.
* * **read** - read a different token from the queried element.
*
* Let's look at an example:
* @usageNotes
* ### Example
*
* {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'}
*
* ### Example
*
* {@example core/di/ts/contentChild/content_child_example.ts region='Component'}
*
* **npm package**: `@angular/core`
*
*
* @Annotation
*/
(selector: Type<any>|Function|string, opts?: {read?: any}): any;
@ -238,7 +231,7 @@ export interface ContentChildDecorator {
/**
* Type of the ContentChild metadata.
*
* See {@link ContentChild}.
* @see `ContentChild`.
*
*
*/
@ -258,21 +251,15 @@ export const ContentChild: ContentChildDecorator = makePropDecorator(
/**
* Type of the ViewChildren decorator / constructor function.
*
* See {@link ViewChildren}.
* @see `ViewChildren`.
*
*
*/
export interface ViewChildrenDecorator {
/**
*
* @usageNotes
*
* {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'}
*
* @description
* Configures a view query.
*
* You can use ViewChildren to get the {@link QueryList} of elements or directives from the
* You can use ViewChildren to get the `QueryList` of elements or directives from the
* view DOM. Any time a child element is added, removed, or moved, the query list will be updated,
* and the changes observable of the query list will emit a new value.
*
@ -283,13 +270,16 @@ export interface ViewChildrenDecorator {
* * **selector** - the directive type or the name used for querying.
* * **read** - read a different token from the queried elements.
*
* Let's look at an example:
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'}
*
* ### Example
*
* {@example core/di/ts/viewChildren/view_children_example.ts region='Component'}
*
* **npm package**: `@angular/core`
*
*
* @Annotation
*/
(selector: Type<any>|Function|string, opts?: {read?: any}): any;
@ -298,15 +288,12 @@ export interface ViewChildrenDecorator {
/**
* Type of the ViewChildren metadata.
*
*
*/
export type ViewChildren = Query;
/**
* ViewChildren decorator and metadata.
*
*
* @Annotation
*/
export const ViewChildren: ViewChildrenDecorator = makePropDecorator(
@ -317,17 +304,10 @@ export const ViewChildren: ViewChildrenDecorator = makePropDecorator(
/**
* Type of the ViewChild decorator / constructor function.
*
* See {@link ViewChild}
*
*
* @see `ViewChild`.
*/
export interface ViewChildDecorator {
/**
*
* @usageNotes
*
* {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'}
*
* @description
* Configures a view query.
*
@ -342,11 +322,16 @@ export interface ViewChildDecorator {
* * **selector** - the directive type or the name used for querying.
* * **read** - read a different token from the queried elements.
*
* @usageNotes
*
* ### Example
*
* {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'}
*
* ### Example
*
* {@example core/di/ts/viewChild/view_child_example.ts region='Component'}
*
* **npm package**: `@angular/core`
*
*
* @Annotation
*/
(selector: Type<any>|Function|string, opts?: {read?: any}): any;
@ -355,15 +340,12 @@ export interface ViewChildDecorator {
/**
* Type of the ViewChild metadata.
*
*
*/
export type ViewChild = Query;
/**
* ViewChild decorator and metadata.
*
*
* @Annotation
*/
export const ViewChild: ViewChildDecorator = makePropDecorator(

155
packages/core/src/metadata/directives.ts
View File

@ -16,25 +16,9 @@ import {ViewEncapsulation} from './view';
/**
* Type of the Directive decorator / constructor function.
*
*
*/
export interface DirectiveDecorator {
/**
* @usageNotes
*
* ```
* import {Directive} from '@angular/core';
*
* @Directive({
* selector: 'my-directive',
* })
* export class MyDirective {
* }
* ```
*
* @description
*
* Marks a class as an Angular directive and collects directive configuration
* metadata.
*
@ -65,13 +49,24 @@ export interface DirectiveDecorator {
* * **queries** - configure queries that can be injected into the component
* * **selector** - css selector that identifies this component in a template
*
* @usageNotes
*
* ```
* import {Directive} from '@angular/core';
*
* @Directive({
* selector: 'my-directive',
* })
* export class MyDirective {
* }
* ```
*
* @Annotation
*/
(obj: Directive): TypeDecorator;
/**
* See the {@link Directive} decorator.
* See the `Directive` decorator.
*/
new (obj: Directive): Directive;
}
@ -92,7 +87,7 @@ export interface Directive {
* - `:not(sub_selector)`: select only if the element does not match the `sub_selector`.
* - `selector1, selector2`: select if either `selector1` or `selector2` matches.
*
*
* @usageNotes
* ### Example
*
* Suppose we have a directive with an `input[type=text]` selector.
@ -124,6 +119,7 @@ export interface Directive {
*
* When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`.
*
* @usageNotes
* ### Example
*
* The following example creates a component with two data-bound properties.
@ -153,7 +149,6 @@ export interface Directive {
* })
* class App {}
* ```
*
*/
inputs?: string[];
@ -169,6 +164,7 @@ export interface Directive {
* - `directiveProperty` specifies the component property that emits events.
* - `bindingProperty` specifies the DOM property the event handler is attached to.
*
* @usageNotes
* ### Example
*
* ```typescript
@ -198,14 +194,17 @@ export interface Directive {
* everyFiveSeconds() { console.log('five seconds'); }
* }
* ```
*
*/
outputs?: string[];
/**
* Specify the events, actions, properties and attributes related to the host element.
*
* ## Host Listeners
* @usageNotes
* The key corresponds to the name of the event, property or attribute on the host to
* bind. The value is formatted differently depending upon the type of the binding.
*
* ### Host Listeners
*
* Specifies which DOM events a directive listens to via a set of `(event)` to `method`
* key-value pairs:
@ -220,8 +219,6 @@ export interface Directive {
*
* When writing a directive event binding, you can also refer to the $event local variable.
*
* ### Example
*
* The following example declares a directive that attaches a click listener to the button and
* counts clicks.
*
@ -247,15 +244,13 @@ export interface Directive {
* class App {}
* ```
*
* ## Host Property Bindings
* ### Host Property Bindings
*
* Specifies which DOM properties a directive updates.
*
* Angular automatically checks host property bindings during change detection.
* If a binding changes, it will update the host element of the directive.
*
* ### Example
*
* The following example creates a directive that sets the `valid` and `invalid` classes
* on the DOM element that has ngModel directive on it.
*
@ -282,12 +277,10 @@ export interface Directive {
* }
* ```
*
* ## Attributes
* ### Attributes
*
* Specifies static attributes that should be propagated to a host element.
*
* ### Example
*
* In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
* (here: `<div>` ) will ensure that this element will get the "button" role.
*
@ -308,7 +301,8 @@ export interface Directive {
* Defines the set of injectable objects that are visible to a Directive and its light DOM
* children.
*
* ## Simple Example
* @usageNotes
* ### Simple Example
*
* Here is an example of a class that can be injected:
*
@ -339,7 +333,8 @@ export interface Directive {
/**
* Defines the name that can be used in the template to assign this directive to a variable.
*
* ## Simple Example
* @usageNotes
* ### Simple Example
*
* ```
* @Directive({
@ -366,6 +361,7 @@ export interface Directive {
* Content queries are set before the `ngAfterContentInit` callback is called.
* View queries are set before the `ngAfterViewInit` callback is called.
*
* @usageNotes
* ### Example
*
* ```
@ -397,7 +393,6 @@ export interface Directive {
/**
* Directive decorator and metadata.
*
*
* @Annotation
*/
export const Directive: DirectiveDecorator = makeDecorator(
@ -406,16 +401,9 @@ export const Directive: DirectiveDecorator = makeDecorator(
/**
* Type of the Component decorator / constructor function.
*
*
*/
export interface ComponentDecorator {
/**
* @usageNotes
*
* {@example core/ts/metadata/metadata.ts region='component'}
*
* @description
* Marks a class as an Angular component and collects component configuration
* metadata.
*
@ -459,24 +447,22 @@ export interface ComponentDecorator {
* * **templateUrl** - url to an external file containing a template for the view
* * **viewProviders** - list of providers available to this component and its view children
*
* @usageNotes
* ### Example
*
* {@example core/ts/metadata/metadata.ts region='component'}
*
*
* @Annotation
*/
(obj: Component): TypeDecorator;
/**
* See the {@link Component} decorator.
* See the `Component` decorator.
*/
new (obj: Component): Component;
}
/**
* Type of the Component metadata.
*
*
*/
export interface Component extends Directive {
/**
@ -493,7 +479,8 @@ export interface Component extends Directive {
/**
* Defines the set of injectable objects that are visible to its view DOM children.
*
* ## Simple Example
* @usageNotes
* ### Simple Example
*
* Here is an example of a class that can be injected:
*
@ -535,8 +522,8 @@ export interface Component extends Directive {
* In CommonJS, this can always be set to `module.id`, similarly SystemJS exposes `__moduleName`
* variable within each module.
*
*
* ## Simple Example
* @usageNotes
* ### Simple Example
*
* ```
* @Directive({
@ -553,7 +540,7 @@ export interface Component extends Directive {
/**
* Specifies a template URL for an Angular component.
*
*Only one of `templateUrl` or `template` can be defined per View.
* Only one of `templateUrl` or `template` can be defined per View.
*/
templateUrl?: string;
@ -586,9 +573,12 @@ export interface Component extends Directive {
*
* For animations to be available for use, animation state changes are placed within
* {@link trigger animation triggers} which are housed inside of the `animations` annotation
* metadata. Within a trigger both {@link state state} and {@link transition transition} entries
* metadata. Within a trigger both `state` and `transition` entries
* can be placed.
*
* @usageNotes
* ### Example
*
* ```typescript
* @Component({
* selector: 'animation-cmp',
@ -636,28 +626,26 @@ export interface Component extends Directive {
* Please visit each of the animation DSL functions listed below to gain a better understanding
* of how and why they are used for crafting animations in Angular:
*
* - {@link trigger trigger()}
* - {@link state state()}
* - {@link transition transition()}
* - {@link group group()}
* - {@link sequence sequence()}
* - {@link style style()}
* - {@link animate animate()}
* - {@link keyframes keyframes()}
* - `trigger()`
* - `state()`
* - `transition()`
* - `group()`
* - `sequence()`
* - `style()`
* - `animate()`
* - `keyframes()`
*/
animations?: any[];
/**
* Specifies how the template and the styles should be encapsulated:
* - {@link ViewEncapsulation#Native `ViewEncapsulation.Native`} to use shadow roots - only works
* if natively available on the platform,
* - {@link ViewEncapsulation#Emulated `ViewEncapsulation.Emulated`} to use shimmed CSS that
* emulates the native behavior,
* - {@link ViewEncapsulation#None `ViewEncapsulation.None`} to use global CSS without any
* encapsulation.
* - `ViewEncapsulation.Native` to use shadow roots - only works if natively available on the
* platform,
* - `ViewEncapsulation.Emulated` to use shimmed CSS that emulates the native behavior,
* - `ViewEncapsulation.None` to use global CSS without any encapsulation.
*
* When no `encapsulation` is defined for the component, the default value from the
* {@link CompilerOptions} is used. The default is `ViewEncapsulation.Emulated`}. Provide a new
* `CompilerOptions` is used. The default is `ViewEncapsulation.Emulated`. Provide a new
* `CompilerOptions` to override this value.
*
* If the encapsulation is set to `ViewEncapsulation.Emulated` and the component has no `styles`
@ -673,13 +661,13 @@ export interface Component extends Directive {
/**
* Defines the components that should be compiled as well when
* this component is defined. For each components listed here,
* Angular will create a {@link ComponentFactory} and store it in the
* {@link ComponentFactoryResolver}.
* Angular will create a `ComponentFactory` and store it in the
* `ComponentFactoryResolver`.
*/
entryComponents?: Array<Type<any>|any[]>;
/**
* If {@link Component#preserveWhitespaces Component.preserveWhitespaces} is set to `false`
* If `Component.preserveWhitespaces` is set to `false`
* potentially superfluous whitespace characters (ones matching the `\s` character class in
* JavaScript regular expressions) will be removed from a compiled template. This can greatly
* reduce AOT-generated code size as well as speed up view creation.
@ -750,7 +738,6 @@ export interface Component extends Directive {
/**
* Component decorator and metadata.
*
*
* @Annotation
*/
export const Component: ComponentDecorator = makeDecorator(
@ -760,8 +747,6 @@ export const Component: ComponentDecorator = makeDecorator(
/**
* Type of the Pipe decorator / constructor function.
*
*
*/
export interface PipeDecorator {
/**
@ -774,15 +759,13 @@ export interface PipeDecorator {
(obj: Pipe): TypeDecorator;
/**
* See the {@link Pipe} decorator.
* See the `Pipe` decorator.
*/
new (obj: Pipe): Pipe;
}
/**
* Type of the Pipe metadata.
*
*
*/
export interface Pipe {
/**
@ -810,11 +793,10 @@ export interface Pipe {
* Pipe decorator and metadata.
*
* Use the `@Pipe` annotation to declare that a given class is a pipe. A pipe
* class must also implement {@link PipeTransform} interface.
* class must also implement `PipeTransform` interface.
*
* To use the pipe include a reference to the pipe class in
* {@link NgModule#declarations}.
*
* `NgModule.declarations`.
*
* @Annotation
*/
@ -865,7 +847,6 @@ export interface InputDecorator {
*
* class App {}
* ```
*
*/
(bindingPropertyName?: string): any;
new (bindingPropertyName?: string): any;
@ -873,8 +854,6 @@ export interface InputDecorator {
/**
* Type of the Input metadata.
*
*
*/
export interface Input {
/**
@ -886,7 +865,6 @@ export interface Input {
/**
* Input decorator and metadata.
*
*
* @Annotation
*/
export const Input: InputDecorator =
@ -894,8 +872,6 @@ export const Input: InputDecorator =
/**
* Type of the Output decorator / constructor function.
*
*
*/
export interface OutputDecorator {
/**
@ -908,6 +884,7 @@ export interface OutputDecorator {
* used when instantiating a component in the template. When not provided,
* the name of the decorated property is used.
*
* @usageNotes
* ### Example
*
* ```typescript
@ -944,15 +921,12 @@ export interface OutputDecorator {
/**
* Type of the Output metadata.
*
*
*/
export interface Output { bindingPropertyName?: string; }
/**
* Output decorator and metadata.
*
*
* @Annotation
*/
export const Output: OutputDecorator =
@ -961,8 +935,6 @@ export const Output: OutputDecorator =
/**
* Type of the HostBinding decorator / constructor function.
*
*
*/
export interface HostBindingDecorator {
/**
@ -975,6 +947,7 @@ export interface HostBindingDecorator {
* name of the host element that will be updated. When not provided,
* the class property name is used.
*
* @usageNotes
* ### Example
*
* The following example creates a directive that sets the `valid` and `invalid` classes
@ -996,7 +969,6 @@ export interface HostBindingDecorator {
* prop;
* }
* ```
*
*/
(hostPropertyName?: string): any;
new (hostPropertyName?: string): any;
@ -1004,15 +976,12 @@ export interface HostBindingDecorator {
/**
* Type of the HostBinding metadata.
*
*
*/
export interface HostBinding { hostPropertyName?: string; }
/**
* HostBinding decorator and metadata.
*
*
* @Annotation
*/
export const HostBinding: HostBindingDecorator =
@ -1021,8 +990,6 @@ export const HostBinding: HostBindingDecorator =
/**
* Type of the HostListener decorator / constructor function.
*
*
*/
export interface HostListenerDecorator {
/**
@ -1032,6 +999,7 @@ export interface HostListenerDecorator {
*
* If the decorated method returns `false`, then `preventDefault` is applied on the DOM event.
*
* @usageNotes
* ### Example
*
* The following example declares a directive that attaches a click listener to the button and
@ -1063,8 +1031,6 @@ export interface HostListenerDecorator {
/**
* Type of the HostListener metadata.
*
*
*/
export interface HostListener {
eventName?: string;
@ -1074,7 +1040,6 @@ export interface HostListener {
/**
* HostListener decorator and metadata.
*
*
* @Annotation
*/
export const HostListener: HostListenerDecorator =