From cb1922f9efeb87924f4318b4d4c19c5717875159 Mon Sep 17 00:00:00 2001 From: Ralph Wang Date: Thu, 7 Dec 2023 17:18:12 +0800 Subject: [PATCH] fix: normalized ts --- packages/animations/src/animation_builder.ts | 2 +- packages/animations/src/animation_metadata.ts | 278 +++++++++--------- .../ng_package/cross_entry_points_imports.ts | 1 + packages/benchpress/src/sampler.ts | 2 + .../benchpress/src/web_driver_extension.ts | 6 +- packages/common/http/src/client.ts | 32 +- packages/common/http/src/interceptor.ts | 5 +- packages/common/http/src/module.ts | 1 + .../generate-locales-tool/day-periods.ts | 5 +- packages/common/src/directives/ng_class.ts | 9 +- .../src/directives/ng_component_outlet.ts | 16 +- packages/common/src/directives/ng_for_of.ts | 8 +- .../ng_optimized_image/ng_optimized_image.ts | 25 +- .../preload-link-creator.ts | 9 +- packages/common/src/directives/ng_plural.ts | 7 +- packages/common/src/directives/ng_switch.ts | 8 +- .../src/directives/ng_template_outlet.ts | 4 +- packages/common/src/i18n/format_date.ts | 2 + packages/common/src/i18n/locale_data_api.ts | 25 +- packages/common/src/i18n/localization.ts | 2 + .../src/location/hash_location_strategy.ts | 1 + packages/common/src/location/location.ts | 2 +- .../common/src/location/location_strategy.ts | 1 + packages/common/src/pipes/async_pipe.ts | 1 - packages/common/src/pipes/date_pipe.ts | 171 ++++++----- packages/common/src/pipes/i18n_plural_pipe.ts | 2 +- packages/common/src/pipes/i18n_select_pipe.ts | 1 - packages/common/src/pipes/json_pipe.ts | 1 - packages/common/src/pipes/keyvalue_pipe.ts | 2 +- packages/common/src/pipes/number_pipe.ts | 71 ++--- packages/common/src/pipes/slice_pipe.ts | 25 +- .../testing/src/mock_platform_location.ts | 5 +- packages/common/upgrade/src/location_shim.ts | 9 +- packages/common/upgrade/src/params.ts | 6 +- .../src/ngtsc/annotations/common/src/api.ts | 6 +- .../ngtsc/annotations/common/src/metadata.ts | 1 + .../annotations/ng_module/src/handler.ts | 1 + .../src/ngtsc/annotations/src/injectable.ts | 1 + .../src/ngtsc/core/api/src/interfaces.ts | 4 +- .../src/ngtsc/core/api/src/public_options.ts | 6 +- .../src/ngtsc/core/src/compiler.ts | 1 + .../src/ngtsc/cycles/test/util.ts | 5 +- .../src/ngtsc/diagnostics/src/error_code.ts | 12 + .../diagnostics/src/error_details_base_url.ts | 6 +- .../src/ngtsc/docs/src/decorator_extractor.ts | 2 + .../src/ngtsc/file_system/src/types.ts | 3 +- .../src/ngtsc/imports/src/alias.ts | 1 + .../src/ngtsc/imports/src/core.ts | 2 + .../src/ngtsc/imports/src/default.ts | 3 +- .../src/patch_alias_reference_resolution.ts | 10 +- .../src/ngtsc/partial_evaluator/src/result.ts | 6 +- .../src/ngtsc/reflection/src/host.ts | 3 + .../src/ngtsc/reflection/src/typescript.ts | 11 +- .../src/ngtsc/transform/src/transform.ts | 1 + .../ngtsc/translator/src/api/ast_factory.ts | 3 +- packages/compiler-cli/src/ngtsc/tsc_plugin.ts | 1 + .../src/ngtsc/typecheck/api/checker.ts | 10 +- .../src/ngtsc/typecheck/api/completion.ts | 6 +- .../src/ngtsc/typecheck/api/symbols.ts | 16 +- .../checks/invalid_banana_in_box/index.ts | 3 +- .../src/ngtsc/typecheck/src/environment.ts | 3 +- .../ngtsc/typecheck/src/type_check_block.ts | 3 + .../ngtsc/typecheck/src/type_constructor.ts | 2 +- packages/compiler-cli/src/transformers/api.ts | 1 + .../downlevel_decorators_transform.ts | 17 +- .../compiler-cli/src/transformers/program.ts | 1 - .../compiler-cli/src/typescript_support.ts | 9 +- packages/compiler-cli/src/version_helpers.ts | 3 +- .../standalone/module_optimization.ts | 2 +- .../ng_modules/forward_refs.ts | 2 +- .../r3_view_compiler/interpolations/test.ts | 2 +- .../di/providedin_forwardref.ts | 2 +- .../element_attributes/empty_attributes.ts | 2 +- .../element_attributes/i18n_root_node.ts | 2 +- .../element_attributes/invalid_i18n_meta.ts | 2 +- .../element_attributes/meaning_description.ts | 2 +- .../element_attributes/ng-template_basic.ts | 2 +- .../element_attributes/static_attributes.ts | 2 +- .../static_attributes_structural.ts | 2 +- .../r3_view_compiler_i18n/es5_support/test.ts | 2 +- .../legacy_disabled.ts | 2 +- .../namespaces/foreign_object.ts | 2 +- .../namespaces/namespaced_div.ts | 2 +- .../comments_in_translated_text.ts | 2 +- .../nested_nodes/directives.ts | 2 +- .../nested_nodes/empty_content.ts | 2 +- .../nested_nodes/escape_quotes.ts | 2 +- .../nested_nodes/nested_templates.ts | 2 +- .../nested_nodes/nested_templates_context.ts | 2 +- .../nested_nodes/plain_text_messages.ts | 2 +- .../nested_nodes/self_closing.ts | 2 +- .../duplicate_content.ts | 2 +- .../nested_ng-container_const.ts | 2 +- .../nested_templates.ts | 2 +- .../ng-container_with_non_text_content.ts | 2 +- .../self_closing_ng-container.ts | 2 +- .../self_closing_tags.ts | 2 +- .../single_ng-template.ts | 2 +- .../structural_directives.ts | 2 +- .../ng-container_ng-template.ts | 2 +- .../self-closing_i18n_instructions/styles.ts | 2 +- .../text_only_content.ts | 2 +- .../preserve_inner_content.ts | 2 +- .../interpolation_with_pipe.ts | 2 +- .../compliance/test_helpers/compile_test.ts | 3 +- .../test_helpers/get_compliance_tests.ts | 10 +- .../compiler/src/compiler_facade_interface.ts | 7 +- packages/compiler/src/core.ts | 10 + .../compiler/src/expression_parser/ast.ts | 11 +- .../compiler/src/expression_parser/parser.ts | 11 +- .../compiler/src/i18n/extractor_merger.ts | 1 + .../src/ml_parser/html_whitespaces.ts | 2 + packages/compiler/src/ml_parser/lexer.ts | 4 +- .../src/output/abstract_js_emitter.ts | 3 +- packages/compiler/src/output/output_ast.ts | 5 +- .../src/output/output_jit_trusted_types.ts | 1 + packages/compiler/src/render3/partial/api.ts | 10 +- .../src/render3/r3_class_metadata_compiler.ts | 2 + packages/compiler/src/render3/r3_factory.ts | 5 + packages/compiler/src/render3/r3_jit.ts | 1 + .../src/render3/r3_module_compiler.ts | 4 +- packages/compiler/src/render3/view/api.ts | 5 + .../compiler/src/render3/view/i18n/meta.ts | 5 +- .../compiler/src/render3/view/template.ts | 23 +- .../src/schema/dom_security_schema.ts | 5 +- .../src/schema/trusted_types_sinks.ts | 5 +- packages/compiler/src/selector.ts | 8 +- .../template/pipeline/ir/src/expression.ts | 3 +- .../template/pipeline/ir/src/ops/update.ts | 2 + .../src/template/pipeline/src/ingest.ts | 18 +- .../pipeline/src/phases/generate_variables.ts | 12 +- .../src/phases/next_context_merging.ts | 7 +- .../src/phases/variable_optimization.ts | 20 +- packages/core/primitives/signals/src/watch.ts | 2 + .../standalone-migration/prune-modules.ts | 2 + .../core/schematics/utils/ng_decorators.ts | 1 + packages/core/src/application_config.ts | 1 - packages/core/src/application_init.ts | 8 +- packages/core/src/application_ref.ts | 20 +- packages/core/src/application_tokens.ts | 10 +- .../change_detection/change_detector_ref.ts | 4 +- .../differs/default_iterable_differ.ts | 18 +- .../differs/iterable_differs.ts | 7 +- .../differs/keyvalue_differs.ts | 2 + .../src/compiler/compiler_facade_interface.ts | 7 +- packages/core/src/debug/debug_node.ts | 26 +- packages/core/src/defer/instructions.ts | 5 +- packages/core/src/defer/interfaces.ts | 3 +- packages/core/src/defer/utils.ts | 5 +- packages/core/src/di/forward_ref.ts | 7 +- packages/core/src/di/inject_switch.ts | 6 +- packages/core/src/di/injectable.ts | 11 +- packages/core/src/di/injection_token.ts | 1 + packages/core/src/di/injector.ts | 5 +- .../core/src/di/injector_compatibility.ts | 7 +- packages/core/src/di/interface/defs.ts | 7 +- packages/core/src/di/interface/provider.ts | 12 +- packages/core/src/di/jit/environment.ts | 1 + packages/core/src/error_details_base_url.ts | 6 +- packages/core/src/errors.ts | 16 +- packages/core/src/hydration/annotate.ts | 18 +- packages/core/src/hydration/compression.ts | 8 +- packages/core/src/hydration/interfaces.ts | 11 +- .../core/src/hydration/node_lookup_utils.ts | 2 + packages/core/src/hydration/utils.ts | 12 +- packages/core/src/i18n/tokens.ts | 4 +- .../core/src/interface/lifecycle_hooks.ts | 22 +- packages/core/src/interface/simple_change.ts | 2 - packages/core/src/interface/type.ts | 3 + packages/core/src/linker/compiler.ts | 3 +- packages/core/src/linker/destroy_ref.ts | 3 + .../src/linker/ng_module_factory_loader.ts | 2 + packages/core/src/linker/query_list.ts | 4 +- .../core/src/linker/view_container_ref.ts | 32 +- packages/core/src/metadata/di.ts | 167 ++++++----- packages/core/src/metadata/directives.ts | 55 ++-- packages/core/src/metadata/ng_module.ts | 21 +- .../core/src/metadata/resource_loading.ts | 2 +- packages/core/src/metadata/schema.ts | 3 +- packages/core/src/metadata/view.ts | 3 + packages/core/src/r3_symbols.ts | 1 + .../src/reflection/reflection_capabilities.ts | 5 +- packages/core/src/render/api_flags.ts | 6 +- .../core/src/render3/after_render_hooks.ts | 14 +- packages/core/src/render3/component.ts | 22 +- .../core/src/render3/context_discovery.ts | 6 +- .../debug/framework_injector_profiler.ts | 6 +- .../src/render3/debug/injector_profiler.ts | 10 +- packages/core/src/render3/definition.ts | 41 ++- packages/core/src/render3/deps_tracker/api.ts | 1 + packages/core/src/render3/di.ts | 7 +- packages/core/src/render3/errors.ts | 3 +- .../features/host_directives_feature.ts | 1 + .../src/render3/features/providers_feature.ts | 2 +- packages/core/src/render3/hooks.ts | 43 +-- .../render3/i18n/i18n_insert_before_index.ts | 1 + packages/core/src/render3/i18n/i18n_parse.ts | 22 +- .../core/src/render3/i18n/i18n_postprocess.ts | 23 +- .../core/src/render3/instructions/advance.ts | 2 +- .../render3/instructions/change_detection.ts | 9 +- .../instructions/class_map_interpolation.ts | 4 +- .../src/render3/instructions/control_flow.ts | 4 +- .../core/src/render3/instructions/element.ts | 1 - .../render3/instructions/element_container.ts | 1 - .../instructions/element_validation.ts | 2 + .../src/render3/instructions/host_property.ts | 2 - .../core/src/render3/instructions/i18n.ts | 20 +- .../i18n_icu_container_visitor.ts | 1 + .../src/render3/instructions/interpolation.ts | 2 + .../core/src/render3/instructions/listener.ts | 1 - .../src/render3/instructions/projection.ts | 4 +- .../core/src/render3/instructions/property.ts | 1 - .../core/src/render3/instructions/render.ts | 6 +- .../core/src/render3/instructions/shared.ts | 14 +- .../instructions/style_map_interpolation.ts | 4 +- .../core/src/render3/instructions/styling.ts | 17 +- .../instructions/text_interpolation.ts | 5 +- .../core/src/render3/interfaces/definition.ts | 17 +- packages/core/src/render3/interfaces/i18n.ts | 11 +- .../core/src/render3/interfaces/injector.ts | 66 +++-- packages/core/src/render3/interfaces/node.ts | 136 ++++++--- .../core/src/render3/interfaces/projection.ts | 13 +- packages/core/src/render3/interfaces/query.ts | 14 +- .../core/src/render3/interfaces/styling.ts | 6 + packages/core/src/render3/interfaces/view.ts | 98 +++--- packages/core/src/render3/jit/environment.ts | 1 + .../core/src/render3/list_reconciliation.ts | 7 +- .../core/src/render3/node_manipulation.ts | 41 ++- .../core/src/render3/node_selector_matcher.ts | 30 +- packages/core/src/render3/pipe.ts | 6 + packages/core/src/render3/pure_function.ts | 9 +- .../core/src/render3/reactivity/asserts.ts | 1 - packages/core/src/render3/state.ts | 27 +- .../src/render3/styling/static_styling.ts | 6 +- .../src/render3/styling/style_binding_list.ts | 70 +++-- .../src/render3/styling/styling_parser.ts | 11 + .../core/src/render3/util/discovery_utils.ts | 10 +- .../render3/util/injector_discovery_utils.ts | 39 +-- packages/core/src/render3/util/view_utils.ts | 7 +- packages/core/src/render3/view_ref.ts | 4 + .../core/src/sanitization/sanitization.ts | 5 - .../core/src/sanitization/url_sanitizer.ts | 5 +- packages/core/src/testability/testability.ts | 2 + packages/core/src/util/array_utils.ts | 61 ++-- packages/core/src/util/coercion.ts | 19 +- packages/core/src/util/ng_dev_mode.ts | 6 +- packages/core/src/zone/ng_zone.ts | 6 +- .../core/test/linker/resource_loader_mock.ts | 1 + packages/core/test/render3/is_shape_of.ts | 1 + packages/core/test/render3/matchers.ts | 6 + packages/core/test/render3/utils.ts | 1 - packages/core/testing/src/fake_async.ts | 7 +- packages/core/testing/src/test_bed.ts | 7 +- .../elements/src/create-custom-element.ts | 1 - packages/elements/src/utils.ts | 1 + .../src/directives/default_value_accessor.ts | 1 - packages/forms/src/directives/ng_form.ts | 4 +- packages/forms/src/directives/ng_model.ts | 9 +- .../forms/src/directives/ng_model_group.ts | 1 - .../radio_control_value_accessor.ts | 1 - .../form_control_directive.ts | 2 - .../reactive_directives/form_control_name.ts | 2 - .../form_group_directive.ts | 3 +- .../reactive_directives/form_group_name.ts | 4 - .../select_control_value_accessor.ts | 1 - packages/forms/src/directives/validators.ts | 4 - packages/forms/src/form_builder.ts | 25 +- packages/forms/src/form_providers.ts | 16 +- packages/forms/src/model/abstract_model.ts | 95 +++--- packages/forms/src/model/form_array.ts | 74 +++-- packages/forms/src/model/form_control.ts | 30 +- packages/forms/src/model/form_group.ts | 63 ++-- packages/forms/src/validators.ts | 14 +- packages/forms/test/util.ts | 11 +- .../src/references_and_rename.ts | 5 +- packages/language-service/src/ts_utils.ts | 2 + packages/localize/index.ts | 14 +- .../localize/src/localize/src/localize.ts | 15 +- .../extract/translation_files/icu_parsing.ts | 10 +- .../src/extract/translation_files/utils.ts | 5 +- .../translate/source_files/locale_plugin.ts | 1 + .../src/backend-service.ts | 3 +- .../src/http-client-backend-service.ts | 2 + .../src/interfaces.ts | 2 + .../platform-browser/animations/src/module.ts | 5 +- packages/platform-browser/src/browser.ts | 4 +- packages/platform-browser/src/dom/debug/by.ts | 6 + packages/platform-browser/src/hydration.ts | 10 +- .../platform-browser/testing/src/matchers.ts | 9 + .../platform-server/src/provide_server.ts | 1 + packages/platform-server/src/utils.ts | 23 +- packages/router/src/directives/router_link.ts | 23 +- .../src/directives/router_link_active.ts | 2 +- packages/router/src/events.ts | 18 +- packages/router/src/models.ts | 46 +-- packages/router/src/navigation_transition.ts | 23 +- packages/router/src/page_title_strategy.ts | 1 + packages/router/src/provide_router.ts | 27 +- packages/router/src/route_reuse_strategy.ts | 2 +- packages/router/src/router.ts | 6 +- packages/router/src/router_config.ts | 20 +- packages/router/src/router_config_loader.ts | 1 + packages/router/src/router_module.ts | 5 +- packages/router/src/router_state.ts | 1 - .../router/src/statemanager/state_manager.ts | 8 +- packages/router/src/url_tree.ts | 30 +- packages/router/src/utils/navigations.ts | 6 +- packages/router/src/utils/type_guards.ts | 3 +- packages/service-worker/cli/sha1.ts | 1 + packages/service-worker/src/update.ts | 20 +- packages/service-worker/worker/src/adapter.ts | 1 + .../worker/src/named-cache-storage.ts | 2 + packages/service-worker/worker/src/sha1.ts | 1 + .../service-worker/worker/testing/utils.ts | 1 + .../upgrade/src/common/src/component_info.ts | 3 +- .../src/common/src/downgrade_component.ts | 11 +- .../src/common/src/downgrade_injectable.ts | 4 +- .../src/dynamic/src/upgrade_adapter.ts | 20 +- .../upgrade/static/src/angular1_providers.ts | 1 - .../upgrade/static/src/downgrade_module.ts | 4 +- .../upgrade/static/src/upgrade_component.ts | 4 +- packages/upgrade/static/src/upgrade_module.ts | 1 + .../zone.js/lib/zone-spec/fake-async-test.ts | 2 +- .../zone.js/lib/zone.configurations.api.ts | 15 +- packages/zone.js/lib/zone.ts | 47 ++- 325 files changed, 2219 insertions(+), 1451 deletions(-) diff --git a/packages/animations/src/animation_builder.ts b/packages/animations/src/animation_builder.ts index 46dedf51b62..ac36c1da8f8 100644 --- a/packages/animations/src/animation_builder.ts +++ b/packages/animations/src/animation_builder.ts @@ -26,7 +26,7 @@ import {AnimationPlayer} from './players/animation_player'; * do need to, follow these steps: * * 1. Use the [AnimationBuilder.build](api/animations/AnimationBuilder#build)() method - * to create a programmatic animation. The method returns an `AnimationFactory` instance. + * to create a programmatic animation. The method returns an `AnimationFactory` instance. * * 2. Use the factory object to create an `AnimationPlayer` and attach it to a DOM element. * diff --git a/packages/animations/src/animation_metadata.ts b/packages/animations/src/animation_metadata.ts index 8a8e81adda7..5302adf1e39 100644 --- a/packages/animations/src/animation_metadata.ts +++ b/packages/animations/src/animation_metadata.ts @@ -40,9 +40,11 @@ export declare type AnimateTimings = { * An easing style that controls how an animations step accelerates * and decelerates during its run time. An easing function such as `cubic-bezier()`, * or one of the following constants: + * * - `ease-in` * - `ease-out` * - `ease-in-and-out` + * */ easing: string | null }; @@ -462,10 +464,9 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * @param name An identifying string. * @param definitions An animation definition object, containing an array of * [`state()`](api/animations/state) and `transition()` declarations. - * * @return An object that encapsulates the trigger data. - * * @usageNotes + * * Define an animation trigger in the `animations` section of `@Component` metadata. * In the template, reference the trigger by name and bind it to a trigger expression that * evaluates to a defined animation state, using the following format: @@ -510,13 +511,14 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * ``` * * ### Using an inline function + * * The `transition` animation method also supports reading an inline function which can decide * if its associated animation should be run. * * ```typescript * // this method is run each time the `myAnimationTrigger` trigger value changes. * function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key: - string]: any}): boolean { + * string]: any}): boolean { * // notice that `element` and `params` are also available here * return toState == 'yes-please-animate'; * } @@ -538,6 +540,7 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * ``` * * ### Disabling Animations + * * When true, the special animation control binding `@.disabled` binding prevents * all animations from rendering. * Place the `@.disabled` binding on an element to disable @@ -570,6 +573,7 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * along with any inner animations. * * ### Disable animations application-wide + * * When an area of the template is set to have animations disabled, * **all** inner components have their animations disabled as well. * This means that you can disable all animations for an app @@ -589,12 +593,14 @@ export interface AnimationStaggerMetadata extends AnimationMetadata { * ``` * * ### Overriding disablement of inner animations + * * Despite inner animations being disabled, a parent animation can `query()` * for inner elements located in disabled areas of the template and still animate * them if needed. This is also the case for when a sub animation is * queried by a parent and then later animated using `animateChild()`. * * ### Detecting when an animation is disabled + * * If a region of the DOM (or the entire application) has its animations disabled, the animation * trigger callbacks still fire, but for zero seconds. When the callback fires, it provides * an instance of an `AnimationEvent`. If animations are disabled, @@ -610,18 +616,20 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati * Defines an animation step that combines styling information with timing information. * * @param timings Sets `AnimateTimings` for the parent animation. - * A string in the format "duration [delay] [easing]". - * - Duration and delay are expressed as a number and optional time unit, - * such as "1s" or "10ms" for one second and 10 milliseconds, respectively. - * The default unit is milliseconds. - * - The easing value controls how the animation accelerates and decelerates - * during its runtime. Value is one of `ease`, `ease-in`, `ease-out`, - * `ease-in-out`, or a `cubic-bezier()` function call. - * If not supplied, no easing is applied. + * A string in the format "duration [delay][easing]". + * + * - Duration and delay are expressed as a number and optional time unit, + * such as "1s" or "10ms" for one second and 10 milliseconds, respectively. + * The default unit is milliseconds. + * - The easing value controls how the animation accelerates and decelerates + * during its runtime. Value is one of `ease`, `ease-in`, `ease-out`, + * `ease-in-out`, or a `cubic-bezier()` function call. + * If not supplied, no easing is applied. * * For example, the string "1s 100ms ease-out" specifies a duration of * 1000 milliseconds, and delay of 100 ms, and the "ease-out" easing style, * which decelerates near the end of the duration. + * * @param styles Sets AnimationStyles for the parent animation. * A function call to either `style()` or `keyframes()` * that returns a collection of CSS style entries to be applied to the parent animation. @@ -629,31 +637,36 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati * This is useful when describing an animation step that will complete an animation; * see "Animating to the final state" in `transitions()`. * @returns An object that encapsulates the animation step. - * * @usageNotes + * * Call within an animation `sequence()`, `{@link animations/group group()}`, or * `transition()` call to specify an animation step * that applies given style data to the parent animation for a given amount of time. * * ### Syntax Examples + * * **Timing examples** * * The following examples show various `timings` specifications. + * * - `animate(500)` : Duration is 500 milliseconds. * - `animate("1s")` : Duration is 1000 milliseconds. * - `animate("100ms 0.5s")` : Duration is 100 milliseconds, delay is 500 milliseconds. * - `animate("5s ease-in")` : Duration is 5000 milliseconds, easing in. * - `animate("5s 10ms cubic-bezier(.17,.67,.88,.1)")` : Duration is 5000 milliseconds, delay is 10 - * milliseconds, easing according to a bezier curve. + * milliseconds, easing according to a bezier curve. * * **Style examples** * * The following example calls `style()` to set a single CSS style. + * * ```typescript * animate(500, style({ background: "red" })) * ``` + * * The following example calls `keyframes()` to set a CSS style * to different values for successive keyframes. + * * ```typescript * animate(500, keyframes( * [ @@ -673,13 +686,13 @@ export function animate( /** * @description Defines a list of animation steps to be run in parallel. - * * @param steps An array of animation step objects. + * * - When steps are defined by `style()` or `animate()` - * function calls, each call within the group is executed instantly. + * function calls, each call within the group is executed instantly. * - To specify offset styles to be applied at a later time, define steps with - * `keyframes()`, or use `animate()` calls with a delay value. - * For example: + * `keyframes()`, or use `animate()` calls with a delay value. + * For example: * * ```typescript * group([ @@ -691,9 +704,7 @@ export function animate( * @param options An options object containing a delay and * developer-defined parameters that provide styling defaults and * can be overridden on invocation. - * * @return An object that encapsulates the group data. - * * @usageNotes * Grouped animations are useful when a series of styles must be * animated at different starting times and closed off at different ending times. @@ -701,7 +712,6 @@ export function animate( * When called within a `sequence()` or a * `transition()` call, does not continue to the next * instruction until all of the inner animation steps have completed. - * * @publicApi */ export function group( @@ -713,6 +723,7 @@ export function group( * Defines a list of animation steps to be run sequentially, one by one. * * @param steps An array of animation step objects. + * * - Steps defined by `style()` calls apply the styling data immediately. * - Steps defined by `animate()` calls apply the styling data over time * as specified by the timing data. @@ -727,21 +738,18 @@ export function group( * @param options An options object containing a delay and * developer-defined parameters that provide styling defaults and * can be overridden on invocation. - * * @return An object that encapsulates the sequence data. - * * @usageNotes * When you pass an array of steps to a * `transition()` call, the steps run sequentially by default. * Compare this to the `{@link animations/group group()}` call, which runs animation steps in - *parallel. + * parallel. * * When a sequence is used within a `{@link animations/group group()}` or a `transition()` call, * execution continues to the next instruction only after each of the inner animation * steps have completed. - * * @publicApi - **/ + */ export function sequence( steps: AnimationMetadata[], options: AnimationOptions|null = null): AnimationSequenceMetadata { return {type: AnimationMetadataType.Sequence, steps, options}; @@ -750,20 +758,20 @@ export function sequence( /** * Declares a key/value object containing CSS properties/styles that * can then be used for an animation [`state`](api/animations/state), within an animation - *`sequence`, or as styling data for calls to `animate()` and `keyframes()`. + * `sequence`, or as styling data for calls to `animate()` and `keyframes()`. * * @param tokens A set of CSS styles or HTML styles associated with an animation state. * The value can be any of the following: + * * - A key-value style pair associating a CSS property with a value. * - An array of key-value style pairs. - * - An asterisk (*), to use auto-styling, where styles are derived from the element - * being animated and applied to the animation when it starts. + * - An asterisk (\*), to use auto-styling, where styles are derived from the element + * being animated and applied to the animation when it starts. * * Auto-styling can be used to define a state that depends on layout or other * environmental factors. * * @return An object that encapsulates the style data. - * * @usageNotes * The following examples create animation styles that collect a set of * CSS property values: @@ -783,9 +791,8 @@ export function sequence( * style({ height: 0 }), * animate("1s", style({ height: "*" })) * ``` - * * @publicApi - **/ + */ export function style(tokens: '*'|{[key: string]: string | number}| Array<'*'|{[key: string]: string | number}>): AnimationStyleMetadata { return {type: AnimationMetadataType.Style, styles: tokens, offset: null}; @@ -799,11 +806,11 @@ export function style(tokens: '*'|{[key: string]: string | number}| * cases: * * - `void` You can associate styles with this name to be used when - * the element is detached from the application. For example, when an `ngIf` evaluates - * to false, the state of the associated element is void. - * - `*` (asterisk) Indicates the default state. You can associate styles with this name - * to be used as the fallback when the state that is being animated is not declared - * within the trigger. + * the element is detached from the application. For example, when an `ngIf` evaluates + * to false, the state of the associated element is void. + * - `*` (asterisk) Indicates the default state. You can associate styles with this name + * to be used as the fallback when the state that is being animated is not declared + * within the trigger. * * @param styles A set of CSS styles associated with this state, created using the * `style()` function. @@ -811,15 +818,13 @@ export function style(tokens: '*'|{[key: string]: string | number}| * @param options Parameters that can be passed to the state when it is invoked. * 0 or more key-value pairs. * @return An object that encapsulates the new state data. - * * @usageNotes * Use the `trigger()` function to register states to an animation trigger. * Use the `transition()` function to animate between states. * When a state is active within a component, its associated styles persist on the element, * even when the animation ends. - * * @publicApi - **/ + */ export function state( name: string, styles: AnimationStyleMetadata, options?: {params: {[name: string]: any}}): AnimationStateMetadata { @@ -880,79 +885,83 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * * @param stateChangeExpr A string with a specific format or a function that specifies when the * animation transition should occur (see [State Change Expression](#state-change-expression)). - * * @param steps One or more animation objects that represent the animation's instructions. - * * @param options An options object that can be used to specify a delay for the animation or provide * custom parameters for it. - * * @returns An object that encapsulates the transition data. - * * @usageNotes * * ### State Change Expression * * The State Change Expression instructs Angular when to run the transition's animations, it can - *either be - * - a string with a specific syntax - * - or a function that compares the previous and current state (value of the expression bound to - * the element's trigger) and returns `true` if the transition should occur or `false` otherwise + * either be + * + * - a string with a specific syntax + * - or a function that compares the previous and current state (value of the expression bound to + * the element's trigger) and returns `true` if the transition should occur or `false` otherwise * * The string format can be: - * - `fromState => toState`, which indicates that the transition's animations should occur then the - * expression bound to the trigger's element goes from `fromState` to `toState` - * - * _Example:_ - * ```typescript - * transition('open => closed', animate('.5s ease-out', style({ height: 0 }) )) - * ``` - * - * - `fromState <=> toState`, which indicates that the transition's animations should occur then - * the expression bound to the trigger's element goes from `fromState` to `toState` or vice versa - * - * _Example:_ - * ```typescript - * transition('enabled <=> disabled', animate('1s cubic-bezier(0.8,0.3,0,1)')) - * ``` - * - * - `:enter`/`:leave`, which indicates that the transition's animations should occur when the - * element enters or exists the DOM - * - * _Example:_ - * ```typescript - * transition(':enter', [ - * style({ opacity: 0 }), - * animate('500ms', style({ opacity: 1 })) - * ]) - * ``` - * - * - `:increment`/`:decrement`, which indicates that the transition's animations should occur when - * the numerical expression bound to the trigger's element has increased in value or decreased - * - * _Example:_ - * ```typescript - * transition(':increment', query('@counter', animateChild())) - * ``` - * - * - a sequence of any of the above divided by commas, which indicates that transition's animations - * should occur whenever one of the state change expressions matches - * - * _Example:_ - * ```typescript - * transition(':increment, * => enabled, :enter', animate('1s ease', keyframes([ - * style({ transform: 'scale(1)', offset: 0}), - * style({ transform: 'scale(1.1)', offset: 0.7}), - * style({ transform: 'scale(1)', offset: 1}) - * ]))), - * ``` + * + * - `fromState => toState`, which indicates that the transition's animations should occur then the + * expression bound to the trigger's element goes from `fromState` to `toState` + * + * _Example:_ + * + * ```typescript + * transition('open => closed', animate('.5s ease-out', style({ height: 0 }) )) + * ``` + * + * - `fromState <=> toState`, which indicates that the transition's animations should occur then + * the expression bound to the trigger's element goes from `fromState` to `toState` or vice versa + * + * _Example:_ + * + * ```typescript + * transition('enabled <=> disabled', animate('1s cubic-bezier(0.8,0.3,0,1)')) + * ``` + * + * - `:enter`/`:leave`, which indicates that the transition's animations should occur when the + * element enters or exists the DOM + * + * _Example:_ + * + * ```typescript + * transition(':enter', [ + * style({ opacity: 0 }), + * animate('500ms', style({ opacity: 1 })) + * ]) + * ``` + * + * - `:increment`/`:decrement`, which indicates that the transition's animations should occur when + * the numerical expression bound to the trigger's element has increased in value or decreased + * + * _Example:_ + * + * ```typescript + * transition(':increment', query('@counter', animateChild())) + * ``` + * + * - a sequence of any of the above divided by commas, which indicates that transition's animations + * should occur whenever one of the state change expressions matches + * + * _Example:_ + * + * ```typescript + * transition(':increment, * => enabled, :enter', animate('1s ease', keyframes([ + * style({ transform: 'scale(1)', offset: 0}), + * style({ transform: 'scale(1.1)', offset: 0.7}), + * style({ transform: 'scale(1)', offset: 1}) + * ]))), + * ``` * * Also note that in such context: - * - `void` can be used to indicate the absence of the element - * - asterisks can be used as wildcards that match any state - * - (as a consequence of the above, `void => *` is equivalent to `:enter` and `* => void` is - * equivalent to `:leave`) - * - `true` and `false` also match expression values of `1` and `0` respectively (but do not match - * _truthy_ and _falsy_ values) + * + * - `void` can be used to indicate the absence of the element + * - asterisks can be used as wildcards that match any state + * - (as a consequence of the above, `void => *` is equivalent to `:enter` and `* => void` is + * equivalent to `:leave`) + * - `true` and `false` also match expression values of `1` and `0` respectively (but do not match + * _truthy_ and _falsy_ values) * *
* @@ -965,7 +974,6 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * a chance to be executed, the only way that such transition can occur is if the element * is exiting the DOM on its own). * - * *
* * ### Animating to a Final State @@ -975,10 +983,9 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * for the element to reach the final state, in such case Angular automatically adds or removes * CSS styles to ensure that the element is in the correct final state. * - * * ### Usage Examples * - * - Transition animations applied based on + * - Transition animations applied based on * the trigger's expression value * * ```HTML @@ -995,32 +1002,32 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe * ]) * ``` * - * - Transition animations applied based on custom logic dependent - * on the trigger's expression value and provided parameters + * - Transition animations applied based on custom logic dependent + * on the trigger's expression value and provided parameters * - * ```HTML - *
- * ... - *
- * ``` - * - * ```typescript - * trigger("myAnimationTrigger", [ - * ..., // states - * transition( - * (fromState, toState, _element, params) => - * ['firststep', 'laststep'].includes(fromState.toLowerCase()) - * && toState === params?.['target'], - * animate('1s') - * ) - * ]) - * ``` + * ```HTML + *
+ * ... + *
+ * ``` + * + * ```typescript + * trigger("myAnimationTrigger", [ + * ..., // states + * transition( + * (fromState, toState, _element, params) => + * ['firststep', 'laststep'].includes(fromState.toLowerCase()) + * && toState === params?.['target'], + * animate('1s') + * ) + * ]) + * ``` * * @publicApi - **/ + */ export function transition( stateChangeExpr: string| ((fromState: string, toState: string, element?: any, params?: {[key: string]: any}) => boolean), @@ -1126,20 +1133,20 @@ export function useAnimation( * * @param selector The element to query, or a set of elements that contain Angular-specific * characteristics, specified with one or more of the following tokens. - * - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements (not - * all elements can be queried via these tokens, see - * [Entering and Leaving Elements](#entering-and-leaving-elements)) - * - `query(":animating")` : Query all currently animating elements. - * - `query("@triggerName")` : Query elements that contain an animation trigger. - * - `query("@*")` : Query all elements that contain an animation triggers. - * - `query(":self")` : Include the current element into the animation sequence. + * + * - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements (not + * all elements can be queried via these tokens, see + * [Entering and Leaving Elements](#entering-and-leaving-elements)) + * - `query(":animating")` : Query all currently animating elements. + * - `query("@triggerName")` : Query elements that contain an animation trigger. + * - `query("@*")` : Query all elements that contain an animation triggers. + * - `query(":self")` : Include the current element into the animation sequence. * * @param animation One or more animation steps to apply to the queried element or elements. * An array is treated as an animation sequence. * @param options An options object. Use the 'limit' field to limit the total number of * items to collect. * @return An object that encapsulates the query data. - * * @usageNotes * * ### Multiple Tokens @@ -1180,8 +1187,9 @@ export function useAnimation( * * The only elements Angular assumes can enter/leave based on their own logic (thus the only * ones that can be queried via the `:enter` and `:leave` tokens) are: - * - Those inserted dynamically (via `ViewContainerRef`) - * - Those that have a structural directive (which, under the hood, are a subset of the above ones) + * + * - Those inserted dynamically (via `ViewContainerRef`) + * - Those that have a structural directive (which, under the hood, are a subset of the above ones) * *
* diff --git a/packages/bazel/src/ng_package/cross_entry_points_imports.ts b/packages/bazel/src/ng_package/cross_entry_points_imports.ts index f3ceb4d10bb..dbe80afde40 100644 --- a/packages/bazel/src/ng_package/cross_entry_points_imports.ts +++ b/packages/bazel/src/ng_package/cross_entry_points_imports.ts @@ -32,6 +32,7 @@ const skipComment = '// @ng_package: ignore-cross-repo-import'; * Such imports are flagged and will be returned in the failure list. Cross * entry-point or package imports result in duplicate code and therefore are * forbidden (unless explicitly opted out via comment - {@link skipComment}). + * */ export function analyzeFileAndEnsureNoCrossImports( file: BazelFileInfo, pkg: PackageMetadata): string[] { diff --git a/packages/benchpress/src/sampler.ts b/packages/benchpress/src/sampler.ts index 7b16afe690d..ff27769561a 100644 --- a/packages/benchpress/src/sampler.ts +++ b/packages/benchpress/src/sampler.ts @@ -18,11 +18,13 @@ import {WebDriverAdapter} from './web_driver_adapter'; /** * The Sampler owns the sample loop: + * * 1. calls the prepare/execute callbacks, * 2. gets data from the metric * 3. asks the validator for a valid sample * 4. reports the new data to the reporter * 5. loop until there is a valid sample + * */ @Injectable() export class Sampler { diff --git a/packages/benchpress/src/web_driver_extension.ts b/packages/benchpress/src/web_driver_extension.ts index e7b3352499c..278428cdfe1 100644 --- a/packages/benchpress/src/web_driver_extension.ts +++ b/packages/benchpress/src/web_driver_extension.ts @@ -75,6 +75,7 @@ export abstract class WebDriverExtension { /** * Format: + * * - cat: category of the event * - name: event name: 'script', 'gc', 'render', ... * - ph: phase: 'B' (begin), 'E' (end), 'X' (Complete event), 'I' (Instant event) @@ -83,8 +84,9 @@ export abstract class WebDriverExtension { * - args: arguments, e.g. {heapSize: 1234} * * Based on [Chrome Trace Event - *Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/edit) - **/ + * Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/edit) + * + */ readPerfLog(): Promise { throw new Error('NYI'); } diff --git a/packages/common/http/src/client.ts b/packages/common/http/src/client.ts index 45a76d65709..e216fcfa754 100644 --- a/packages/common/http/src/client.ts +++ b/packages/common/http/src/client.ts @@ -64,9 +64,10 @@ function addBody( * single data type of the response. * A single overload version of the method handles each response type. * The value of `responseType` cannot be a union, as the combined signature could imply. - + * * * @usageNotes + * * Sample HTTP requests for the [Tour of Heroes](/tutorial/tour-of-heroes/toh-pt0) application. * * ### HTTP Request Example @@ -82,12 +83,13 @@ function addBody( * * Alternatively, the parameter string can be used without invoking HttpParams * by directly joining to the URL. + * * ``` * this.httpClient.request('GET', this.heroesUrl + '?' + 'name=term', {responseType:'json'}); * ``` * - * * ### JSONP Example + * * ``` * requestJsonp(url, callback = 'callback') { * return this.httpClient.jsonp(this.heroesURL, callback); @@ -95,6 +97,7 @@ function addBody( * ``` * * ### PATCH Example + * * ``` * // PATCH one of the heroes' name * patchHero (id: number, heroName: string): Observable<{}> { @@ -106,7 +109,6 @@ function addBody( * * @see [HTTP Guide](guide/understanding-communicating-with-http) * @see [HTTP Request](api/common/http/HttpRequest) - * * @publicApi */ @Injectable() @@ -486,18 +488,20 @@ export class HttpClient { * a URL string as the second, and an options hash containing the request body as the third. * See `addBody()`. In this case, the specified `responseType` and `observe` options determine the * type of returned observable. - * * The `responseType` value determines how a successful response body is parsed. - * * If `responseType` is the default `json`, you can pass a type interface for the resulting - * object as a type parameter to the call. + * + * - The `responseType` value determines how a successful response body is parsed. + * - If `responseType` is the default `json`, you can pass a type interface for the resulting + * object as a type parameter to the call. * * The `observe` value determines the return type, according to what you are interested in * observing. - * * An `observe` value of events returns an observable of the raw `HttpEvent` stream, including - * progress events by default. - * * An `observe` value of response returns an observable of `HttpResponse`, - * where the `T` parameter depends on the `responseType` and any optionally provided type - * parameter. - * * An `observe` value of body returns an observable of `` with the same `T` body type. + * + * - An `observe` value of events returns an observable of the raw `HttpEvent` stream, including + * progress events by default. + * - An `observe` value of response returns an observable of `HttpResponse`, + * where the `T` parameter depends on the `responseType` and any optionally provided type + * parameter. + * - An `observe` value of body returns an observable of `` with the same `T` body type. * */ request(first: string|HttpRequest, url?: string, options: { @@ -2861,9 +2865,9 @@ export class HttpClient { * @param url The endpoint URL. * @param body The resources to add/update. * @param options HTTP options - * * @return An `Observable` of the `HttpResponse` for the request, with a response body - * of type 'Object`. + * of type `Object`. + * */ put(url: string, body: any|null, options: { headers?: HttpHeaders|{[header: string]: string | string[]}, observe: 'response', diff --git a/packages/common/http/src/interceptor.ts b/packages/common/http/src/interceptor.ts index 73ad2cf29d9..069349316b2 100644 --- a/packages/common/http/src/interceptor.ts +++ b/packages/common/http/src/interceptor.ts @@ -94,9 +94,10 @@ export type HttpHandlerFn = (req: HttpRequest) => Observable, next: * HttpHandlerFn) => { @@ -108,6 +109,7 @@ export type HttpHandlerFn = (req: HttpRequest) => Observable, next: * HttpHandlerFn) => { @@ -118,6 +120,7 @@ export type HttpHandlerFn = (req: HttpRequest) => Observable, next: HttpHandlerFn) => Observable>; diff --git a/packages/common/http/src/module.ts b/packages/common/http/src/module.ts index bfa62a1daf8..bb575df211e 100644 --- a/packages/common/http/src/module.ts +++ b/packages/common/http/src/module.ts @@ -53,6 +53,7 @@ export class HttpClientXsrfModule { * Configure XSRF protection. * @param options An object that can specify either or both * cookie name or header name. + * * - Cookie name default is `XSRF-TOKEN`. * - Header name default is `X-XSRF-TOKEN`. * diff --git a/packages/common/locales/generate-locales-tool/day-periods.ts b/packages/common/locales/generate-locales-tool/day-periods.ts index 9a915f9aad1..c6dba0c2579 100644 --- a/packages/common/locales/generate-locales-tool/day-periods.ts +++ b/packages/common/locales/generate-locales-tool/day-periods.ts @@ -44,7 +44,10 @@ export function getDayPeriods(localeData: CldrLocaleData, dayPeriodsList: string /** * Returns day period rules for a locale - * @returns string[] + * @returns + * + * string\[] + * */ export function getDayPeriodRules( localeData: CldrLocaleData, diff --git a/packages/common/src/directives/ng_class.ts b/packages/common/src/directives/ng_class.ts index 563f5eac5f3..1240567fa11 100644 --- a/packages/common/src/directives/ng_class.ts +++ b/packages/common/src/directives/ng_class.ts @@ -16,11 +16,13 @@ const EMPTY_ARRAY: string[] = []; /** * Represents internal object used to track state of each CSS class. There are 3 different (boolean) * flags that, combined together, indicate state of a given CSS class: + * * - enabled: indicates if a class should be present in the DOM (true) or not (false); * - changed: tracks if a class was toggled (added or removed) during the custom dirty-checking - * process; changed classes must be synchronized with the DOM; + * process; changed classes must be synchronized with the DOM; * - touched: tracks if a class is present in the current object bound to the class / ngClass input; - * classes that are not present any more can be removed from the internal data structures; + * classes that are not present any more can be removed from the internal data structures; + * */ interface CssClassState { // PERF: could use a bit mask to represent state as all fields are boolean flags @@ -31,7 +33,6 @@ interface CssClassState { /** * @ngModule CommonModule - * * @usageNotes * ``` * ... @@ -44,12 +45,12 @@ interface CssClassState { * * ... * ``` - * * @description * * Adds and removes CSS classes on an HTML element. * * The CSS classes are updated as follows, depending on the type of the expression evaluation: + * * - `string` - the CSS classes listed in the string (space delimited) are added, * - `Array` - the CSS classes declared as Array elements are added, * - `Object` - keys are CSS classes that get added when the expression given in the value diff --git a/packages/common/src/directives/ng_component_outlet.ts b/packages/common/src/directives/ng_component_outlet.ts index f7e157fa7bd..c5045bd37ae 100644 --- a/packages/common/src/directives/ng_component_outlet.ts +++ b/packages/common/src/directives/ng_component_outlet.ts @@ -22,29 +22,31 @@ import {ComponentRef, createNgModule, Directive, DoCheck, Injector, Input, NgMod * You can control the component creation process by using the following optional attributes: * * * `ngComponentOutletInputs`: Optional component inputs object, which will be bind to the - * component. + * component. * * * `ngComponentOutletInjector`: Optional custom {@link Injector} that will be used as parent for - * the Component. Defaults to the injector of the current view container. + * the Component. Defaults to the injector of the current view container. * * * `ngComponentOutletContent`: Optional list of projectable nodes to insert into the content - * section of the component, if it exists. + * section of the component, if it exists. * * * `ngComponentOutletNgModule`: Optional NgModule class reference to allow loading another - * module dynamically, then loading a component from that module. + * module dynamically, then loading a component from that module. * * * `ngComponentOutletNgModuleFactory`: Deprecated config option that allows providing optional - * NgModule factory to allow loading another module dynamically, then loading a component from that - * module. Use `ngComponentOutletNgModule` instead. + * NgModule factory to allow loading another module dynamically, then loading a component from that + * module. Use `ngComponentOutletNgModule` instead. * * ### Syntax * * Simple + * * ``` * * ``` * * With inputs + * * ``` * @@ -52,6 +54,7 @@ import {ComponentRef, createNgModule, Directive, DoCheck, Injector, Input, NgMod * ``` * * Customized injector/content + * * ``` * diff --git a/packages/common/src/directives/ng_for_of.ts b/packages/common/src/directives/ng_for_of.ts index 53e0016395a..fd768dda187 100644 --- a/packages/common/src/directives/ng_for_of.ts +++ b/packages/common/src/directives/ng_for_of.ts @@ -83,9 +83,9 @@ export class NgForOfContext = NgIterable> { * `NgForOf` provides exported values that can be aliased to local variables. * For example: * - * ``` + * ``` *
  • - * {{i}}/{{users.length}}. {{user}} default + * {{i}}/{{users.length}}. {{user}} default *
  • * ``` * @@ -93,8 +93,8 @@ export class NgForOfContext = NgIterable> { * * - `$implicit: T`: The value of the individual items in the iterable (`ngForOf`). * - `ngForOf: NgIterable`: The value of the iterable expression. Useful when the expression is - * more complex then a property access, for example when using the async pipe (`userStreams | - * async`). + * more complex then a property access, for example when using the async pipe (`userStreams | + * async`). * - `index: number`: The index of the current item in the iterable. * - `count: number`: The length of the iterable. * - `first: boolean`: True when the item is the first item in the iterable. diff --git a/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts b/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts index 27c2bf81cad..755dbdcbde3 100644 --- a/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts +++ b/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts @@ -91,11 +91,13 @@ export const BUILT_IN_LOADERS = [imgixLoaderInfo, imageKitLoaderInfo, cloudinary * * `NgOptimizedImage` ensures that the loading of the Largest Contentful Paint (LCP) image is * prioritized by: + * * - Automatically setting the `fetchpriority` attribute on the `` tag * - Lazy loading non-priority images by default * - Automatically generating a preconnect link tag in the document head * * In addition, the directive: + * * - Generates appropriate asset URLs if a corresponding `ImageLoader` function is provided * - Automatically generates a srcset * - Requires that `width` and `height` are set @@ -103,13 +105,16 @@ export const BUILT_IN_LOADERS = [imgixLoaderInfo, imageKitLoaderInfo, cloudinary * - Warns if the image will be visually distorted when rendered * * @usageNotes + * * The `NgOptimizedImage` directive is marked as [standalone](guide/standalone-components) and can * be imported directly. * * Follow the steps below to enable and use the directive: + * * 1. Import it into the necessary NgModule or a standalone Component. * 2. Optionally provide an `ImageLoader` if you use an image hosting service. * 3. Update the necessary `` tags in templates and replace `src` attributes with `ngSrc`. + * * Using a `ngSrc` allows the directive to control when the `src` gets set, which triggers an image * download. * @@ -151,6 +156,7 @@ export const BUILT_IN_LOADERS = [imgixLoaderInfo, imageKitLoaderInfo, cloudinary * ``` * * The `NgOptimizedImage` directive provides the following functions: + * * - `provideCloudflareLoader` * - `provideCloudinaryLoader` * - `provideImageKitLoader` @@ -227,10 +233,12 @@ export class NgOptimizedImage implements OnInit, OnChanges, OnDestroy { * descriptors to generate the final `srcset` property of the image. * * Example: + * * ``` * => * * ``` + * */ @Input() ngSrcset!: string; @@ -248,8 +256,9 @@ export class NgOptimizedImage implements OnInit, OnChanges, OnDestroy { /** * For responsive images: the intrinsic height of the image in pixels. - * For fixed size images: the desired rendered height of the image in pixels.* The intrinsic - * height of the image in pixels. + * For fixed size images: the desired rendered height of the image in pixels. + * The intrinsic height of the image in pixels. + * */ @Input({transform: numberAttribute}) height: number|undefined; @@ -536,7 +545,10 @@ export class NgOptimizedImage implements OnInit, OnChanges, OnDestroy { } } -/***** Helpers *****/ +/** + * \*\* Helpers + * + */ /** * Sorts provided config breakpoints and uses defaults. @@ -549,7 +561,10 @@ function processConfig(config: ImageConfig): ImageConfig { return Object.assign({}, IMAGE_CONFIG_DEFAULTS, config, sortedBreakpoints); } -/***** Assert functions *****/ +/** + * \*\* Assert functions + * + */ /** * Verifies that there is no `src` set on a host element. @@ -741,8 +756,10 @@ function assertGreaterThanZero(dir: NgOptimizedImage, inputValue: unknown, input /** * Verifies that the rendered image is not visually distorted. Effectively this is checking: + * * - Whether the "width" and "height" attributes reflect the actual dimensions of the image. * - Whether image styling is "correct" (see below for a longer explanation). + * */ function assertNoImageDistortion( dir: NgOptimizedImage, img: HTMLImageElement, renderer: Renderer2) { diff --git a/packages/common/src/directives/ng_optimized_image/preload-link-creator.ts b/packages/common/src/directives/ng_optimized_image/preload-link-creator.ts index 28382b592ac..fb2c6394885 100644 --- a/packages/common/src/directives/ng_optimized_image/preload-link-creator.ts +++ b/packages/common/src/directives/ng_optimized_image/preload-link-creator.ts @@ -14,12 +14,15 @@ import {RuntimeErrorCode} from '../../errors'; import {DEFAULT_PRELOADED_IMAGES_LIMIT, PRELOADED_IMAGES} from './tokens'; /** - * @description Contains the logic needed to track and add preload link tags to the `` tag. It + * @description + * + * Contains the logic needed to track and add preload link tags to the `` tag. It * will also track what images have already had preload link tags added so as to not duplicate link * tags. * * In dev mode this service will validate that the number of preloaded images does not exceed the * configured default preloaded images limit: {@link DEFAULT_PRELOADED_IMAGES_LIMIT}. + * */ @Injectable({providedIn: 'root'}) export class PreloadLinkCreator { @@ -27,7 +30,9 @@ export class PreloadLinkCreator { private readonly document = inject(DOCUMENT); /** - * @description Add a preload `` to the `` of the `index.html` that is served from the + * @description + * + * Add a preload `` to the `` of the `index.html` that is served from the * server while using Angular Universal and SSR to kick off image loads for high priority images. * * The `sizes` (passed in from the user) and `srcset` (parsed and formatted from `ngSrcset`) diff --git a/packages/common/src/directives/ng_plural.ts b/packages/common/src/directives/ng_plural.ts index 4428ade4701..c8511126cbf 100644 --- a/packages/common/src/directives/ng_plural.ts +++ b/packages/common/src/directives/ng_plural.ts @@ -14,7 +14,6 @@ import {SwitchView} from './ng_switch'; /** * @ngModule CommonModule - * * @usageNotes * ``` * @@ -23,7 +22,6 @@ import {SwitchView} from './ng_switch'; * there are a few * * ``` - * * @description * * Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization. @@ -34,6 +32,7 @@ import {SwitchView} from './ng_switch'; * To use this directive you must provide a container element that sets the `[ngPlural]` attribute * to a switch expression. Inner elements with a `[ngPluralCase]` will display based on their * expression: + * * - if `[ngPluralCase]` is set to a value starting with `=`, it will only display if the value * matches the switch expression exactly, * - otherwise, the view will be treated as a "category match", and will only display if exact @@ -84,19 +83,19 @@ export class NgPlural { /** * @ngModule CommonModule - * * @description * * Creates a view that will be added/removed from the parent {@link NgPlural} when the * given expression matches the plural expression according to CLDR rules. * * @usageNotes + * * ``` * * ... * ... * - *``` + * ``` * * See {@link NgPlural} for more details and example. * diff --git a/packages/common/src/directives/ng_switch.ts b/packages/common/src/directives/ng_switch.ts index 0c7bf9953c0..520d1beaf1a 100644 --- a/packages/common/src/directives/ng_switch.ts +++ b/packages/common/src/directives/ng_switch.ts @@ -39,16 +39,18 @@ export class SwitchView { /** * @ngModule CommonModule - * * @description + * * The `[ngSwitch]` directive on a container specifies an expression to match against. * The expressions to match are provided by `ngSwitchCase` directives on views within the container. + * * - Every view that matches is rendered. * - If there are no matches, a view with the `ngSwitchDefault` directive is rendered. * - Elements within the `[NgSwitch]` statement but outside of any `NgSwitchCase` - * or `ngSwitchDefault` directive are preserved at the location. + * or `ngSwitchDefault` directive are preserved at the location. * * @usageNotes + * * Define a container element for the directive, and specify the switch expression * to match against as an attribute: * @@ -83,6 +85,7 @@ export class SwitchView { * ``` * * The following example shows how cases can be nested: + * * ``` * * ... @@ -101,7 +104,6 @@ export class SwitchView { * @see {@link NgSwitchCase} * @see {@link NgSwitchDefault} * @see [Structural Directives](guide/structural-directives) - * */ @Directive({ selector: '[ngSwitch]', diff --git a/packages/common/src/directives/ng_template_outlet.ts b/packages/common/src/directives/ng_template_outlet.ts index 46068372c8c..903d8501371 100644 --- a/packages/common/src/directives/ng_template_outlet.ts +++ b/packages/common/src/directives/ng_template_outlet.ts @@ -10,7 +10,6 @@ import {Directive, EmbeddedViewRef, Injector, Input, OnChanges, SimpleChange, Si /** * @ngModule CommonModule - * * @description * * Inserts an embedded view from a prepared `TemplateRef`. @@ -18,8 +17,8 @@ import {Directive, EmbeddedViewRef, Injector, Input, OnChanges, SimpleChange, Si * You can attach a context object to the `EmbeddedViewRef` by setting `[ngTemplateOutletContext]`. * `[ngTemplateOutletContext]` should be an object, the object's keys will be available for binding * by the local template `let` declarations. - * * @usageNotes + * * ``` * * ``` @@ -44,6 +43,7 @@ export class NgTemplateOutlet implements OnChanges { * object, the object's keys will be available for binding by the local template `let` * declarations. * Using the key `$implicit` in the context object will set its value as default. + * */ @Input() public ngTemplateOutletContext: C|null = null; diff --git a/packages/common/src/i18n/format_date.ts b/packages/common/src/i18n/format_date.ts index 67011fbc895..563666c2579 100644 --- a/packages/common/src/i18n/format_date.ts +++ b/packages/common/src/i18n/format_date.ts @@ -743,6 +743,7 @@ function convertTimezoneToLocal(date: Date, timezone: string, reverse: boolean): * Converts a value to date. * * Supported input formats: + * * - `Date` * - number: timestamp * - string: numeric (e.g. "1234"), ISO and date strings in a format supported by @@ -750,6 +751,7 @@ function convertTimezoneToLocal(date: Date, timezone: string, reverse: boolean): * Note: ISO strings without time return a date without timeoffset. * * Throws if unable to convert to a date. + * */ export function toDate(value: string|number|Date): Date { if (isDate(value)) { diff --git a/packages/common/src/i18n/locale_data_api.ts b/packages/common/src/i18n/locale_data_api.ts index 43dda49612d..9b93f992dd3 100644 --- a/packages/common/src/i18n/locale_data_api.ts +++ b/packages/common/src/i18n/locale_data_api.ts @@ -88,8 +88,8 @@ export enum TranslationWidth { */ export enum FormatWidth { /** - * For `en-US`, 'M/d/yy, h:mm a'` - * (Example: `6/15/15, 9:03 AM`) + * For `en-US`, 'M/d/yy, h:mm a'`(Example:`6/15/15, 9:03 AM\`) + * */ Short, /** @@ -419,16 +419,16 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str * * Here are the special characters used in number patterns: * - * | Symbol | Meaning | - * |--------|---------| - * | . | Replaced automatically by the character used for the decimal point. | - * | , | Replaced by the "grouping" (thousands) separator. | - * | 0 | Replaced by a digit (or zero if there aren't enough digits). | - * | # | Replaced by a digit (or nothing if there aren't enough). | - * | ¤ | Replaced by a currency symbol, such as $ or USD. | - * | % | Marks a percent format. The % symbol may change position, but must be retained. | - * | E | Marks a scientific format. The E symbol may change position, but must be retained. | - * | ' | Special characters used as literal characters are quoted with ASCII single quotes. | + * | Symbol | Meaning | + * | ------ | ---------------------------------------------------------------------------------- | + * | . | Replaced automatically by the character used for the decimal point. | + * | , | Replaced by the "grouping" (thousands) separator. | + * | 0 | Replaced by a digit (or zero if there aren't enough digits). | + * | # | Replaced by a digit (or nothing if there aren't enough). | + * | ¤ | Replaced by a currency symbol, such as $ or USD. | + * | % | Marks a percent format. The % symbol may change position, but must be retained. | + * | E | Marks a scientific format. The E symbol may change position, but must be retained. | + * | ' | Special characters used as literal characters are quoted with ASCII single quotes. | * * @param locale A locale code for the locale format rules to use. * @param type The type of numeric value to be formatted (such as `Decimal` or `Currency`.) @@ -436,7 +436,6 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str * @see {@link NumberFormatStyle} * @see [CLDR website](http://cldr.unicode.org/translation/number-patterns) * @see [Internationalization (i18n) Guide](/guide/i18n-overview) - * * @publicApi */ export function getLocaleNumberFormat(locale: string, type: NumberFormatStyle): string { diff --git a/packages/common/src/i18n/localization.ts b/packages/common/src/i18n/localization.ts index 2d4c30e5945..3786b1d011b 100644 --- a/packages/common/src/i18n/localization.ts +++ b/packages/common/src/i18n/localization.ts @@ -24,8 +24,10 @@ export abstract class NgLocalization { /** * Returns the plural category for a given value. + * * - "=value" when the case exists, * - the plural category otherwise + * */ export function getPluralCategory( value: number, cases: string[], ngLocalization: NgLocalization, locale?: string): string { diff --git a/packages/common/src/location/hash_location_strategy.ts b/packages/common/src/location/hash_location_strategy.ts index b352eebc02c..c01f27dc765 100644 --- a/packages/common/src/location/hash_location_strategy.ts +++ b/packages/common/src/location/hash_location_strategy.ts @@ -16,6 +16,7 @@ import {joinWithSlash, normalizeQueryParams} from './util'; /** * @description + * * A {@link LocationStrategy} used to configure the {@link Location} service to * represent its state in the * [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) diff --git a/packages/common/src/location/location.ts b/packages/common/src/location/location.ts index 9532a34d4b9..60755abff68 100644 --- a/packages/common/src/location/location.ts +++ b/packages/common/src/location/location.ts @@ -27,7 +27,6 @@ export interface PopStateEvent { * * Depending on the `LocationStrategy` used, `Location` persists * to the URL's path or the URL's hash segment. - * * @usageNotes * * It's better to use the `Router.navigate()` service to trigger route changes. Use @@ -37,6 +36,7 @@ export interface PopStateEvent { * `Location` is responsible for normalizing the URL against the application's base href. * A normalized URL is absolute from the URL host, includes the application's base href, and has no * trailing slash: + * * - `/my/app/user/123` is normalized * - `my/app/user/123` **is not** normalized * - `/my/app/user/123/` **is not** normalized diff --git a/packages/common/src/location/location_strategy.ts b/packages/common/src/location/location_strategy.ts index 564be4142cb..b8570927d3c 100644 --- a/packages/common/src/location/location_strategy.ts +++ b/packages/common/src/location/location_strategy.ts @@ -73,6 +73,7 @@ export const APP_BASE_HREF = new InjectionToken('appBaseHref'); /** * @description + * * A {@link LocationStrategy} used to configure the {@link Location} service to * represent its state in the * [path](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) of the diff --git a/packages/common/src/pipes/async_pipe.ts b/packages/common/src/pipes/async_pipe.ts index 6778b3ec5b9..8c7b628f473 100644 --- a/packages/common/src/pipes/async_pipe.ts +++ b/packages/common/src/pipes/async_pipe.ts @@ -64,7 +64,6 @@ const _subscribableStrategy = new SubscribableStrategy(); * changes. When the component gets destroyed, the `async` pipe unsubscribes automatically to avoid * potential memory leaks. When the reference of the expression changes, the `async` pipe * automatically unsubscribes from the old `Observable` or `Promise` and subscribes to the new one. - * * @usageNotes * * ### Examples diff --git a/packages/common/src/pipes/date_pipe.ts b/packages/common/src/pipes/date_pipe.ts index 0540317efb3..56e3b9c16fa 100644 --- a/packages/common/src/pipes/date_pipe.ts +++ b/packages/common/src/pipes/date_pipe.ts @@ -24,13 +24,13 @@ export const DATE_PIPE_DEFAULT_TIMEZONE = new InjectionToken('DATE_PIPE_ /** * DI token that allows to provide default configuration for the `DatePipe` instances in an * application. The value is an object which can include the following fields: + * * - `dateFormat`: configures the default date format. If not provided, the `DatePipe` - * will use the 'mediumDate' as a value. + * will use the 'mediumDate' as a value. * - `timezone`: configures the default timezone. If not provided, the `DatePipe` will - * use the end-user's local system timezone. + * use the end-user's local system timezone. * * @see {@link DatePipeConfig} - * * @usageNotes * * Various date pipe default values can be overwritten by providing this token with @@ -39,6 +39,7 @@ export const DATE_PIPE_DEFAULT_TIMEZONE = new InjectionToken('DATE_PIPE_ * For example: * * Override the default date format by providing a value using the token: + * * ```typescript * providers: [ * {provide: DATE_PIPE_DEFAULT_OPTIONS, useValue: {dateFormat: 'shortDate'}} @@ -46,11 +47,13 @@ export const DATE_PIPE_DEFAULT_TIMEZONE = new InjectionToken('DATE_PIPE_ * ``` * * Override the default timezone by providing a value using the token: + * * ```typescript * providers: [ * {provide: DATE_PIPE_DEFAULT_OPTIONS, useValue: {timezone: '-1200'}} * ] * ``` + * */ export const DATE_PIPE_DEFAULT_OPTIONS = new InjectionToken('DATE_PIPE_DEFAULT_OPTIONS'); @@ -78,10 +81,7 @@ export const DATE_PIPE_DEFAULT_OPTIONS = * parameter of the pipe, or by setting the default through the `DATE_PIPE_DEFAULT_OPTIONS` * injection token. The value that is passed in as the second parameter takes precedence over * the one defined using the injection token. - * * @see {@link formatDate} - * - * * @usageNotes * * The result of this pipe is not reevaluated when the input is mutated. To avoid the need to @@ -90,93 +90,92 @@ export const DATE_PIPE_DEFAULT_OPTIONS = * * ### Pre-defined format options * - * | Option | Equivalent to | Examples (given in `en-US` locale) | - * |---------------|-------------------------------------|-------------------------------------------------| - * | `'short'` | `'M/d/yy, h:mm a'` | `6/15/15, 9:03 AM` | - * | `'medium'` | `'MMM d, y, h:mm:ss a'` | `Jun 15, 2015, 9:03:01 AM` | - * | `'long'` | `'MMMM d, y, h:mm:ss a z'` | `June 15, 2015 at 9:03:01 AM GMT+1` | - * | `'full'` | `'EEEE, MMMM d, y, h:mm:ss a zzzz'` | `Monday, June 15, 2015 at 9:03:01 AM GMT+01:00` | - * | `'shortDate'` | `'M/d/yy'` | `6/15/15` | - * | `'mediumDate'`| `'MMM d, y'` | `Jun 15, 2015` | - * | `'longDate'` | `'MMMM d, y'` | `June 15, 2015` | - * | `'fullDate'` | `'EEEE, MMMM d, y'` | `Monday, June 15, 2015` | - * | `'shortTime'` | `'h:mm a'` | `9:03 AM` | - * | `'mediumTime'`| `'h:mm:ss a'` | `9:03:01 AM` | - * | `'longTime'` | `'h:mm:ss a z'` | `9:03:01 AM GMT+1` | - * | `'fullTime'` | `'h:mm:ss a zzzz'` | `9:03:01 AM GMT+01:00` | + * | Option | Equivalent to | Examples (given in `en-US` locale) | + * | -------------- | ----------------------------------- | ----------------------------------------------- | + * | `'short'` | `'M/d/yy, h:mm a'` | `6/15/15, 9:03 AM` | + * | `'medium'` | `'MMM d, y, h:mm:ss a'` | `Jun 15, 2015, 9:03:01 AM` | + * | `'long'` | `'MMMM d, y, h:mm:ss a z'` | `June 15, 2015 at 9:03:01 AM GMT+1` | + * | `'full'` | `'EEEE, MMMM d, y, h:mm:ss a zzzz'` | `Monday, June 15, 2015 at 9:03:01 AM GMT+01:00` | + * | `'shortDate'` | `'M/d/yy'` | `6/15/15` | + * | `'mediumDate'` | `'MMM d, y'` | `Jun 15, 2015` | + * | `'longDate'` | `'MMMM d, y'` | `June 15, 2015` | + * | `'fullDate'` | `'EEEE, MMMM d, y'` | `Monday, June 15, 2015` | + * | `'shortTime'` | `'h:mm a'` | `9:03 AM` | + * | `'mediumTime'` | `'h:mm:ss a'` | `9:03:01 AM` | + * | `'longTime'` | `'h:mm:ss a z'` | `9:03:01 AM GMT+1` | + * | `'fullTime'` | `'h:mm:ss a zzzz'` | `9:03:01 AM GMT+01:00` | * * ### Custom format options * * You can construct a format string using symbols to specify the components * of a date-time value, as described in the following table. * Format details depend on the locale. - * Fields marked with (*) are only available in the extra data set for the given locale. - * - * | Field type | Format | Description | Example Value | - * |-------------------- |-------------|---------------------------------------------------------------|------------------------------------------------------------| - * | Era | G, GG & GGG | Abbreviated | AD | - * | | GGGG | Wide | Anno Domini | - * | | GGGGG | Narrow | A | - * | Year | y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 | - * | | yy | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 | - * | | yyy | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 | - * | | yyyy | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 | - * | Week-numbering year | Y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 | - * | | YY | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 | - * | | YYY | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 | - * | | YYYY | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 | - * | Month | M | Numeric: 1 digit | 9, 12 | - * | | MM | Numeric: 2 digits + zero padded | 09, 12 | - * | | MMM | Abbreviated | Sep | - * | | MMMM | Wide | September | - * | | MMMMM | Narrow | S | - * | Month standalone | L | Numeric: 1 digit | 9, 12 | - * | | LL | Numeric: 2 digits + zero padded | 09, 12 | - * | | LLL | Abbreviated | Sep | - * | | LLLL | Wide | September | - * | | LLLLL | Narrow | S | - * | Week of year | w | Numeric: minimum digits | 1... 53 | - * | | ww | Numeric: 2 digits + zero padded | 01... 53 | - * | Week of month | W | Numeric: 1 digit | 1... 5 | - * | Day of month | d | Numeric: minimum digits | 1 | - * | | dd | Numeric: 2 digits + zero padded | 01 | - * | Week day | E, EE & EEE | Abbreviated | Tue | - * | | EEEE | Wide | Tuesday | - * | | EEEEE | Narrow | T | - * | | EEEEEE | Short | Tu | - * | Week day standalone | c, cc | Numeric: 1 digit | 2 | - * | | ccc | Abbreviated | Tue | - * | | cccc | Wide | Tuesday | - * | | ccccc | Narrow | T | - * | | cccccc | Short | Tu | - * | Period | a, aa & aaa | Abbreviated | am/pm or AM/PM | - * | | aaaa | Wide (fallback to `a` when missing) | ante meridiem/post meridiem | - * | | aaaaa | Narrow | a/p | - * | Period* | B, BB & BBB | Abbreviated | mid. | - * | | BBBB | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | - * | | BBBBB | Narrow | md | - * | Period standalone* | b, bb & bbb | Abbreviated | mid. | - * | | bbbb | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | - * | | bbbbb | Narrow | md | - * | Hour 1-12 | h | Numeric: minimum digits | 1, 12 | - * | | hh | Numeric: 2 digits + zero padded | 01, 12 | - * | Hour 0-23 | H | Numeric: minimum digits | 0, 23 | - * | | HH | Numeric: 2 digits + zero padded | 00, 23 | - * | Minute | m | Numeric: minimum digits | 8, 59 | - * | | mm | Numeric: 2 digits + zero padded | 08, 59 | - * | Second | s | Numeric: minimum digits | 0... 59 | - * | | ss | Numeric: 2 digits + zero padded | 00... 59 | - * | Fractional seconds | S | Numeric: 1 digit | 0... 9 | - * | | SS | Numeric: 2 digits + zero padded | 00... 99 | - * | | SSS | Numeric: 3 digits + zero padded (= milliseconds) | 000... 999 | - * | Zone | z, zz & zzz | Short specific non location format (fallback to O) | GMT-8 | - * | | zzzz | Long specific non location format (fallback to OOOO) | GMT-08:00 | - * | | Z, ZZ & ZZZ | ISO8601 basic format | -0800 | - * | | ZZZZ | Long localized GMT format | GMT-8:00 | - * | | ZZZZZ | ISO8601 extended format + Z indicator for offset 0 (= XXXXX) | -08:00 | - * | | O, OO & OOO | Short localized GMT format | GMT-8 | - * | | OOOO | Long localized GMT format | GMT-08:00 | + * Fields marked with (\*) are only available in the extra data set for the given locale. * + * | Field type | Format | Description | Example Value | + * | ------------------- | ----------- | ------------------------------------------------------------ | ---------------------------------------------------------- | + * | Era | G, GG & GGG | Abbreviated | AD | + * | | GGGG | Wide | Anno Domini | + * | | GGGGG | Narrow | A | + * | Year | y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 | + * | | yy | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 | + * | | yyy | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 | + * | | yyyy | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 | + * | Week-numbering year | Y | Numeric: minimum digits | 2, 20, 201, 2017, 20173 | + * | | YY | Numeric: 2 digits + zero padded | 02, 20, 01, 17, 73 | + * | | YYY | Numeric: 3 digits + zero padded | 002, 020, 201, 2017, 20173 | + * | | YYYY | Numeric: 4 digits or more + zero padded | 0002, 0020, 0201, 2017, 20173 | + * | Month | M | Numeric: 1 digit | 9, 12 | + * | | MM | Numeric: 2 digits + zero padded | 09, 12 | + * | | MMM | Abbreviated | Sep | + * | | MMMM | Wide | September | + * | | MMMMM | Narrow | S | + * | Month standalone | L | Numeric: 1 digit | 9, 12 | + * | | LL | Numeric: 2 digits + zero padded | 09, 12 | + * | | LLL | Abbreviated | Sep | + * | | LLLL | Wide | September | + * | | LLLLL | Narrow | S | + * | Week of year | w | Numeric: minimum digits | 1... 53 | + * | | ww | Numeric: 2 digits + zero padded | 01... 53 | + * | Week of month | W | Numeric: 1 digit | 1... 5 | + * | Day of month | d | Numeric: minimum digits | 1 | + * | | dd | Numeric: 2 digits + zero padded | 01 | + * | Week day | E, EE & EEE | Abbreviated | Tue | + * | | EEEE | Wide | Tuesday | + * | | EEEEE | Narrow | T | + * | | EEEEEE | Short | Tu | + * | Week day standalone | c, cc | Numeric: 1 digit | 2 | + * | | ccc | Abbreviated | Tue | + * | | cccc | Wide | Tuesday | + * | | ccccc | Narrow | T | + * | | cccccc | Short | Tu | + * | Period | a, aa & aaa | Abbreviated | am/pm or AM/PM | + * | | aaaa | Wide (fallback to `a` when missing) | ante meridiem/post meridiem | + * | | aaaaa | Narrow | a/p | + * | Period\* | B, BB & BBB | Abbreviated | mid. | + * | | BBBB | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | + * | | BBBBB | Narrow | md | + * | Period standalone\* | b, bb & bbb | Abbreviated | mid. | + * | | bbbb | Wide | am, pm, midnight, noon, morning, afternoon, evening, night | + * | | bbbbb | Narrow | md | + * | Hour 1-12 | h | Numeric: minimum digits | 1, 12 | + * | | hh | Numeric: 2 digits + zero padded | 01, 12 | + * | Hour 0-23 | H | Numeric: minimum digits | 0, 23 | + * | | HH | Numeric: 2 digits + zero padded | 00, 23 | + * | Minute | m | Numeric: minimum digits | 8, 59 | + * | | mm | Numeric: 2 digits + zero padded | 08, 59 | + * | Second | s | Numeric: minimum digits | 0... 59 | + * | | ss | Numeric: 2 digits + zero padded | 00... 59 | + * | Fractional seconds | S | Numeric: 1 digit | 0... 9 | + * | | SS | Numeric: 2 digits + zero padded | 00... 99 | + * | | SSS | Numeric: 3 digits + zero padded (= milliseconds) | 000... 999 | + * | Zone | z, zz & zzz | Short specific non location format (fallback to O) | GMT-8 | + * | | zzzz | Long specific non location format (fallback to OOOO) | GMT-08:00 | + * | | Z, ZZ & ZZZ | ISO8601 basic format | -0800 | + * | | ZZZZ | Long localized GMT format | GMT-8:00 | + * | | ZZZZZ | ISO8601 extended format + Z indicator for offset 0 (= XXXXX) | -08:00 | + * | | O, OO & OOO | Short localized GMT format | GMT-8 | + * | | OOOO | Long localized GMT format | GMT-08:00 | * * ### Format examples * diff --git a/packages/common/src/pipes/i18n_plural_pipe.ts b/packages/common/src/pipes/i18n_plural_pipe.ts index 42d4341576d..51d1b1d2eec 100644 --- a/packages/common/src/pipes/i18n_plural_pipe.ts +++ b/packages/common/src/pipes/i18n_plural_pipe.ts @@ -19,7 +19,6 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g; * @description * * Maps a value to a string that pluralizes the value according to locale rules. - * * @usageNotes * * ### Example @@ -42,6 +41,7 @@ export class I18nPluralPipe implements PipeTransform { * https://unicode-org.github.io/icu/userguide/format_parse/messages/. * @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by * default). + * */ transform(value: number|null|undefined, pluralMap: {[count: string]: string}, locale?: string): string { diff --git a/packages/common/src/pipes/i18n_select_pipe.ts b/packages/common/src/pipes/i18n_select_pipe.ts index f39cfe69172..aa0593f1171 100644 --- a/packages/common/src/pipes/i18n_select_pipe.ts +++ b/packages/common/src/pipes/i18n_select_pipe.ts @@ -18,7 +18,6 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * If none of the keys of the `mapping` match the `value`, then the content * of the `other` key is returned when present, otherwise an empty string is returned. - * * @usageNotes * * ### Example diff --git a/packages/common/src/pipes/json_pipe.ts b/packages/common/src/pipes/json_pipe.ts index aff4747e9dc..8af3664328b 100644 --- a/packages/common/src/pipes/json_pipe.ts +++ b/packages/common/src/pipes/json_pipe.ts @@ -13,7 +13,6 @@ import {Pipe, PipeTransform} from '@angular/core'; * @description * * Converts a value into its JSON-format representation. Useful for debugging. - * * @usageNotes * * The following component uses a JSON pipe to convert an object diff --git a/packages/common/src/pipes/keyvalue_pipe.ts b/packages/common/src/pipes/keyvalue_pipe.ts index 8fdeed22732..58656ebb513 100644 --- a/packages/common/src/pipes/keyvalue_pipe.ts +++ b/packages/common/src/pipes/keyvalue_pipe.ts @@ -32,8 +32,8 @@ export interface KeyValue { * The output array will be ordered by keys. * By default the comparator will be by Unicode point value. * You can optionally pass a compareFn if your keys are complex types. - * * @usageNotes + * * ### Examples * * This examples show how an Object or a Map can be iterated by ngFor with the use of this diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts index 5089a42a170..a742e6473b0 100644 --- a/packages/common/src/pipes/number_pipe.ts +++ b/packages/common/src/pipes/number_pipe.ts @@ -21,9 +21,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * Formats a value according to digit options and locale rules. * Locale determines group sizing and separator, * decimal point character, and other locale-specific configurations. - * * @see {@link formatNumber} - * * @usageNotes * * ### digitsInfo @@ -35,17 +33,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits} * ``` * - * - `minIntegerDigits`: - * The minimum number of integer digits before the decimal point. - * Default is 1. + * - `minIntegerDigits`: + * The minimum number of integer digits before the decimal point. + * Default is 1. * * - `minFractionDigits`: - * The minimum number of digits after the decimal point. - * Default is 0. + * The minimum number of digits after the decimal point. + * Default is 0. * - * - `maxFractionDigits`: - * The maximum number of digits after the decimal point. - * Default is 3. + * - `maxFractionDigits`: + * The maximum number of digits after the decimal point. + * Default is 3. * * If the formatted value is truncated it will be rounded using the "to-nearest" method: * @@ -145,12 +143,14 @@ export class PercentPipe implements PipeTransform { * @param digitsInfo Decimal representation options, specified by a string * in the following format:
    * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. - * - `minIntegerDigits`: The minimum number of integer digits before the decimal point. - * Default is `1`. - * - `minFractionDigits`: The minimum number of digits after the decimal point. - * Default is `0`. - * - `maxFractionDigits`: The maximum number of digits after the decimal point. - * Default is `0`. + * + * - `minIntegerDigits`: The minimum number of integer digits before the decimal point. + * Default is `1`. + * - `minFractionDigits`: The minimum number of digits after the decimal point. + * Default is `0`. + * - `maxFractionDigits`: The maximum number of digits after the decimal point. + * Default is `0`. + * * @param locale A locale code for the locale format rules to use. * When not supplied, uses the value of `LOCALE_ID`, which is `en-US` by default. * See [Setting your app locale](guide/i18n-common-locale-id). @@ -217,28 +217,31 @@ export class CurrencyPipe implements PipeTransform { * such as `USD` for the US dollar and `EUR` for the euro. The default currency code can be * configured using the `DEFAULT_CURRENCY_CODE` injection token. * @param display The format for the currency indicator. One of the following: - * - `code`: Show the code (such as `USD`). - * - `symbol`(default): Show the symbol (such as `$`). - * - `symbol-narrow`: Use the narrow symbol for locales that have two symbols for their - * currency. - * For example, the Canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`. If the - * locale has no narrow symbol, uses the standard symbol for the locale. - * - String: Use the given string value instead of a code or a symbol. - * For example, an empty string will suppress the currency & symbol. - * - Boolean (marked deprecated in v5): `true` for symbol and false for `code`. + * + * - `code`: Show the code (such as `USD`). + * - `symbol`(default): Show the symbol (such as `$`). + * - `symbol-narrow`: Use the narrow symbol for locales that have two symbols for their + * currency. + * For example, the Canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`. If the + * locale has no narrow symbol, uses the standard symbol for the locale. + * - String: Use the given string value instead of a code or a symbol. + * For example, an empty string will suppress the currency & symbol. + * - Boolean (marked deprecated in v5): `true` for symbol and false for `code`. * * @param digitsInfo Decimal representation options, specified by a string * in the following format:
    * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. - * - `minIntegerDigits`: The minimum number of integer digits before the decimal point. - * Default is `1`. - * - `minFractionDigits`: The minimum number of digits after the decimal point. - * Default is `2`. - * - `maxFractionDigits`: The maximum number of digits after the decimal point. - * Default is `2`. - * If not provided, the number will be formatted with the proper amount of digits, - * depending on what the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) specifies. - * For example, the Canadian dollar has 2 digits, whereas the Chilean peso has none. + * + * - `minIntegerDigits`: The minimum number of integer digits before the decimal point. + * Default is `1`. + * - `minFractionDigits`: The minimum number of digits after the decimal point. + * Default is `2`. + * - `maxFractionDigits`: The maximum number of digits after the decimal point. + * Default is `2`. + * If not provided, the number will be formatted with the proper amount of digits, + * depending on what the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) specifies. + * For example, the Canadian dollar has 2 digits, whereas the Chilean peso has none. + * * @param locale A locale code for the locale format rules to use. * When not supplied, uses the value of `LOCALE_ID`, which is `en-US` by default. * See [Setting your app locale](guide/i18n-common-locale-id). diff --git a/packages/common/src/pipes/slice_pipe.ts b/packages/common/src/pipes/slice_pipe.ts index bdf33ae446f..ac85ac27ede 100644 --- a/packages/common/src/pipes/slice_pipe.ts +++ b/packages/common/src/pipes/slice_pipe.ts @@ -15,7 +15,6 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * @description * * Creates a new `Array` or `String` containing a subset (slice) of the elements. - * * @usageNotes * * All behavior is based on the expected behavior of the JavaScript API `Array.prototype.slice()` @@ -54,17 +53,21 @@ export class SlicePipe implements PipeTransform { /** * @param value a list or a string to be sliced. * @param start the starting index of the subset to return: - * - **a positive integer**: return the item at `start` index and all items after - * in the list or string expression. - * - **a negative integer**: return the item at `start` index from the end and all items after - * in the list or string expression. - * - **if positive and greater than the size of the expression**: return an empty list or - * string. - * - **if negative and greater than the size of the expression**: return entire list or string. + * + * - **a positive integer**: return the item at `start` index and all items after + * in the list or string expression. + * - **a negative integer**: return the item at `start` index from the end and all items after + * in the list or string expression. + * - **if positive and greater than the size of the expression**: return an empty list or + * string. + * - **if negative and greater than the size of the expression**: return entire list or string. + * * @param end the ending index of the subset to return: - * - **omitted**: return all items until the end. - * - **if positive**: return all items before `end` index of the list or string. - * - **if negative**: return all items before `end` index from the end of the list or string. + * + * - **omitted**: return all items until the end. + * - **if positive**: return all items before `end` index of the list or string. + * - **if negative**: return all items before `end` index from the end of the list or string. + * */ transform(value: ReadonlyArray, start: number, end?: number): Array; transform(value: null|undefined, start: number, end?: number): null; diff --git a/packages/common/testing/src/mock_platform_location.ts b/packages/common/testing/src/mock_platform_location.ts index 5ab18e1ce76..ab4fc2919b7 100644 --- a/packages/common/testing/src/mock_platform_location.ts +++ b/packages/common/testing/src/mock_platform_location.ts @@ -12,14 +12,14 @@ import {Subject} from 'rxjs'; /** * Parser from https://tools.ietf.org/html/rfc3986#appendix-B - * ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))? + * ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\\?([^#]*))?(#(.*))? * 12 3 4 5 6 7 8 9 * * Example: http://www.ics.uci.edu/pub/ietf/uri/#Related * * Results in: * - * $1 = http: + * $1 = http: * $2 = http * $3 = //www.ics.uci.edu * $4 = www.ics.uci.edu @@ -28,6 +28,7 @@ import {Subject} from 'rxjs'; * $7 = * $8 = #Related * $9 = Related + * */ const urlParse = /^(([^:\/?#]+):)?(\/\/([^\/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?/; diff --git a/packages/common/upgrade/src/location_shim.ts b/packages/common/upgrade/src/location_shim.ts index e959fc118cb..56dfccff224 100644 --- a/packages/common/upgrade/src/location_shim.ts +++ b/packages/common/upgrade/src/location_shim.ts @@ -447,12 +447,12 @@ export class $locationShim { * rules specified in * [RFC 3986](https://tools.ietf.org/html/rfc3986). * - * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo * let absUrl = $location.absUrl(); * // => "http://example.com/#/some/path?foo=bar&baz=xoxo" * ``` + * */ absUrl(): string { return this.$$absUrl; @@ -508,7 +508,6 @@ export class $locationShim { * In contrast to the non-AngularJS version `location.host` which returns `hostname:port`, this * returns the `hostname` portion only. * - * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo * let host = $location.host(); @@ -520,6 +519,7 @@ export class $locationShim { * host = location.host; * // => "example.com:8080" * ``` + * */ host(): string { return this.$$host; @@ -572,7 +572,6 @@ export class $locationShim { * Retrieves a map of the search parameters of the current URL, or changes a search * part and returns a reference to its own instance. * - * * ```js * // given URL http://example.com/#/some/path?foo=bar&baz=xoxo * let searchObject = $location.search(); @@ -591,7 +590,6 @@ export class $locationShim { * * If the argument is a hash object containing an array of values, these values will be encoded * as duplicate search parameters in the URL. - * * @param {(string|Number|Array|boolean)=} paramValue If `search` is a string or number, * then `paramValue` * will override only a single search property. @@ -603,7 +601,6 @@ export class $locationShim { * * If `paramValue` is `true`, the property specified via the first argument will be added with no * value nor trailing equal sign. - * * @return {Object} The parsed `search` object of the current URL, or the changed `search` object. */ search(): {[key: string]: unknown}; @@ -690,7 +687,7 @@ export class $locationShim { * * This method is supported only in HTML5 mode and only in browsers supporting * the HTML5 History API methods such as `pushState` and `replaceState`. If you need to support - * older browsers (like Android < 4.0), don't use this method. + * older browsers (like Android < 4.0), don't use this method. * */ state(): unknown; diff --git a/packages/common/upgrade/src/params.ts b/packages/common/upgrade/src/params.ts index c832d619ffb..616d8f7e0c0 100644 --- a/packages/common/upgrade/src/params.ts +++ b/packages/common/upgrade/src/params.ts @@ -302,11 +302,12 @@ function toKeyValue(obj: {[k: string]: unknown}) { * segment = *pchar * pchar = unreserved / pct-encoded / sub-delims / ":" / "@" * pct-encoded = "%" HEXDIG HEXDIG - * unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + * unreserved = ALPHA / DIGIT / "-" / "." / "\_" / "~" * sub-delims = "!" / "$" / "&" / "'" / "(" / ")" * / "*" / "+" / "," / ";" / "=" * * Logic from https://github.com/angular/angular.js/blob/864c7f0/src/Angular.js#L1437 + * */ function encodeUriSegment(val: string) { return encodeUriQuery(val, true).replace(/%26/g, '&').replace(/%3D/gi, '=').replace(/%2B/gi, '+'); @@ -319,12 +320,13 @@ function encodeUriSegment(val: string) { * encoded per https://tools.ietf.org/html/rfc3986: * query = *( pchar / "/" / "?" ) * pchar = unreserved / pct-encoded / sub-delims / ":" / "@" - * unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" + * unreserved = ALPHA / DIGIT / "-" / "." / "\_" / "~" * pct-encoded = "%" HEXDIG HEXDIG * sub-delims = "!" / "$" / "&" / "'" / "(" / ")" * / "*" / "+" / "," / ";" / "=" * * Logic from https://github.com/angular/angular.js/blob/864c7f0/src/Angular.js#L1456 + * */ function encodeUriQuery(val: string, pctEncodeSpaces: boolean = false) { return encodeURIComponent(val) diff --git a/packages/compiler-cli/src/ngtsc/annotations/common/src/api.ts b/packages/compiler-cli/src/ngtsc/annotations/common/src/api.ts index 2ff84162eab..5ef82593c75 100644 --- a/packages/compiler-cli/src/ngtsc/annotations/common/src/api.ts +++ b/packages/compiler-cli/src/ngtsc/annotations/common/src/api.ts @@ -76,10 +76,12 @@ export interface ResourceLoader { export interface ResourceLoaderContext { /** * The type of the component resource. + * * * Resources referenced via a component's `styles` or `styleUrls` properties are of - * type `style`. + * type `style`. * * Resources referenced via a component's `template` or `templateUrl` properties are of type - * `template`. + * `template`. + * */ type: 'style'|'template'; diff --git a/packages/compiler-cli/src/ngtsc/annotations/common/src/metadata.ts b/packages/compiler-cli/src/ngtsc/annotations/common/src/metadata.ts index 53cc741f90e..83a94ad61d4 100644 --- a/packages/compiler-cli/src/ngtsc/annotations/common/src/metadata.ts +++ b/packages/compiler-cli/src/ngtsc/annotations/common/src/metadata.ts @@ -152,6 +152,7 @@ function decoratorToMetadata( * Whether a given decorator should be treated as an Angular decorator. * * Either it's used in @angular/core, or it's imported from there. + * */ function isAngularDecorator(decorator: Decorator, isCore: boolean): boolean { return isCore || (decorator.import !== null && decorator.import.from === '@angular/core'); diff --git a/packages/compiler-cli/src/ngtsc/annotations/ng_module/src/handler.ts b/packages/compiler-cli/src/ngtsc/annotations/ng_module/src/handler.ts index 6b846cbb6b7..44088ee24b7 100644 --- a/packages/compiler-cli/src/ngtsc/annotations/ng_module/src/handler.ts +++ b/packages/compiler-cli/src/ngtsc/annotations/ng_module/src/handler.ts @@ -165,6 +165,7 @@ export class NgModuleSymbol extends SemanticSymbol { /** * Compiles @NgModule annotations to ngModuleDef fields. + * */ export class NgModuleDecoratorHandler implements DecoratorHandler { diff --git a/packages/compiler-cli/src/ngtsc/annotations/src/injectable.ts b/packages/compiler-cli/src/ngtsc/annotations/src/injectable.ts index be7b3793bcc..608b9c1e440 100644 --- a/packages/compiler-cli/src/ngtsc/annotations/src/injectable.ts +++ b/packages/compiler-cli/src/ngtsc/annotations/src/injectable.ts @@ -174,6 +174,7 @@ export class InjectableDecoratorHandler implements * input metadata needed to run `compileInjectable`. * * A `null` return value indicates this is @Injectable has invalid data. + * */ function extractInjectableMetadata( clazz: ClassDeclaration, decorator: Decorator, diff --git a/packages/compiler-cli/src/ngtsc/core/api/src/interfaces.ts b/packages/compiler-cli/src/ngtsc/core/api/src/interfaces.ts index 072f7a77bd6..4444044a8df 100644 --- a/packages/compiler-cli/src/ngtsc/core/api/src/interfaces.ts +++ b/packages/compiler-cli/src/ngtsc/core/api/src/interfaces.ts @@ -76,8 +76,10 @@ export interface ResourceHost { export interface ResourceHostContext { /** * The type of the component resource. Templates are not yet supported. + * * * Resources referenced via a component's `styles` or `styleUrls` properties are of - * type `style`. + * type `style`. + * */ readonly type: 'style'; /** diff --git a/packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts b/packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts index acf5b3c77ef..feb1b0da567 100644 --- a/packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts +++ b/packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts @@ -384,13 +384,15 @@ export interface I18nOptions { export interface TargetOptions { /** * Specifies the compilation mode to use. The following modes are available: + * * - 'full': generates fully AOT compiled code using Ivy instructions. * - 'partial': generates code in a stable, but intermediate form suitable for publication to NPM. * - 'experimental-local': generates code based on each individual source file without using its - * dependencies. This mode is suitable only for fast edit/refresh during development. It will be - * eventually replaced by the value `local` once the feature is ready to be public. + * dependencies. This mode is suitable only for fast edit/refresh during development. It will be + * eventually replaced by the value `local` once the feature is ready to be public. * * The default value is 'full'. + * */ compilationMode?: 'full'|'partial'|'experimental-local'; } diff --git a/packages/compiler-cli/src/ngtsc/core/src/compiler.ts b/packages/compiler-cli/src/ngtsc/core/src/compiler.ts index 3e07bb8929f..3d63b514886 100644 --- a/packages/compiler-cli/src/ngtsc/core/src/compiler.ts +++ b/packages/compiler-cli/src/ngtsc/core/src/compiler.ts @@ -1191,6 +1191,7 @@ export class NgCompiler { /** * Determine if the given `Program` is @angular/core. + * */ export function isAngularCorePackage(program: ts.Program): boolean { // Look for its_just_angular.ts somewhere in the program. diff --git a/packages/compiler-cli/src/ngtsc/cycles/test/util.ts b/packages/compiler-cli/src/ngtsc/cycles/test/util.ts index 88ba9388bb4..4420788fae6 100644 --- a/packages/compiler-cli/src/ngtsc/cycles/test/util.ts +++ b/packages/compiler-cli/src/ngtsc/cycles/test/util.ts @@ -25,14 +25,15 @@ import {makeProgram} from '../../testing'; * * A more complicated example has a dependency from b.ts to c.ts: "a:b,c;b:c;c". * - * A * preceding a file name in the list of imports indicates that the dependency should be an + * A \* preceding a file name in the list of imports indicates that the dependency should be an * "export" and not an "import" dependency. For example: * - * "a:*b,c;b;c" + * "a:\*b,c;b;c" * * represents a program where a.ts exports from b.ts and imports from c.ts. * * An import can be suffixed with ! to make it a type-only import. + * */ export function makeProgramFromGraph(fs: PathManipulation, graph: string): { program: ts.Program, diff --git a/packages/compiler-cli/src/ngtsc/diagnostics/src/error_code.ts b/packages/compiler-cli/src/ngtsc/diagnostics/src/error_code.ts index f5ec27d15ba..077fd9ec253 100644 --- a/packages/compiler-cli/src/ngtsc/diagnostics/src/error_code.ts +++ b/packages/compiler-cli/src/ngtsc/diagnostics/src/error_code.ts @@ -317,7 +317,9 @@ export enum ErrorCode { * ``` * {{ foo ?? bar }} * ``` + * * When the type of foo doesn't include `null` or `undefined`. + * */ NULLISH_COALESCING_NOT_NULLABLE = 8102, @@ -331,6 +333,7 @@ export enum ErrorCode { * A text attribute is not interpreted as a binding but likely intended to be. * * For example: + * * ``` *
  • {{item["name"]}};
  • * ``` + * */ MISSING_NGFOROF_LET = 8105, /** @@ -374,7 +380,9 @@ export enum ErrorCode { * {{ foo?.['bar'] }} * {{ foo?.() }} * ``` + * * When the type of foo doesn't include `null` or `undefined`. + * */ OPTIONAL_CHAIN_NOT_NULLABLE = 8107, @@ -383,12 +391,14 @@ export enum ErrorCode { * `ngSkipHydration` should not be a binding (it should be a static attribute). * * For example: + * * ``` * * ``` * * `ngSkipHydration` cannot be a binding and can not have values other than "true" or an empty * value + * */ SKIP_HYDRATION_NOT_STATIC = 8108, @@ -396,9 +406,11 @@ export enum ErrorCode { * Signal functions should be invoked when interpolated in templates. * * For example: + * * ``` * {{ mySignal() }} * ``` + * */ INTERPOLATED_SIGNAL_NOT_INVOKED = 8109, diff --git a/packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts b/packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts index 2c7cac3c6f1..d11a04abd87 100644 --- a/packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts +++ b/packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts @@ -10,7 +10,9 @@ * Base URL for the error details page. * * Keep the files below in full sync: - * - packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts - * - packages/core/src/error_details_base_url.ts + * + * - packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts + * - packages/core/src/error_details_base_url.ts + * */ export const ERROR_DETAILS_PAGE_BASE_URL = 'https://angular.io/errors'; diff --git a/packages/compiler-cli/src/ngtsc/docs/src/decorator_extractor.ts b/packages/compiler-cli/src/ngtsc/docs/src/decorator_extractor.ts index 6cd5e3e5caf..679bf281701 100644 --- a/packages/compiler-cli/src/ngtsc/docs/src/decorator_extractor.ts +++ b/packages/compiler-cli/src/ngtsc/docs/src/decorator_extractor.ts @@ -99,11 +99,13 @@ function getDecoratorOptions( * Gets the call signature node that has the decorator's public JsDoc block. * * Every decorator has three parts: + * * - A const that has the actual decorator. * - An interface with the same name as the const that documents the decorator's options. * - An interface suffixed with "Decorator" that has the decorator's call signature and JsDoc block. * * For the description and JsDoc tags, we need the interface suffixed with "Decorator". + * */ function getDecoratorJsDocNode(declaration: ts.VariableDeclaration): ts.HasJSDoc { const name = declaration.name.getText(); diff --git a/packages/compiler-cli/src/ngtsc/file_system/src/types.ts b/packages/compiler-cli/src/ngtsc/file_system/src/types.ts index 6720de0b457..d3b6db097f6 100644 --- a/packages/compiler-cli/src/ngtsc/file_system/src/types.ts +++ b/packages/compiler-cli/src/ngtsc/file_system/src/types.ts @@ -43,7 +43,8 @@ export interface PathManipulation { * * In file-systems that can have multiple file trees the returned path may not actually be * "relative" (i.e. `PathSegment`). For example, Windows can have multiple drives : - * `relative('c:/a/b', 'd:/a/c')` would be `d:/a/c'. + * `relative('c:/a/b', 'd:/a/c')` would be \`d:/a/c'. + * */ relative(from: T, to: T): PathSegment|AbsoluteFsPath; basename(filePath: string, extension?: string): PathSegment; diff --git a/packages/compiler-cli/src/ngtsc/imports/src/alias.ts b/packages/compiler-cli/src/ngtsc/imports/src/alias.ts index 4c41e3cc4a3..a88c2892bdb 100644 --- a/packages/compiler-cli/src/ngtsc/imports/src/alias.ts +++ b/packages/compiler-cli/src/ngtsc/imports/src/alias.ts @@ -43,6 +43,7 @@ const CHARS_TO_ESCAPE = /[^a-zA-Z0-9/_]/g; * came to be in a template's scope (e.g. by which NgModule). * * See the README.md for more information on how aliasing works within the compiler. + * */ export interface AliasingHost { /** diff --git a/packages/compiler-cli/src/ngtsc/imports/src/core.ts b/packages/compiler-cli/src/ngtsc/imports/src/core.ts index 5b67e66e905..28ff4536d7a 100644 --- a/packages/compiler-cli/src/ngtsc/imports/src/core.ts +++ b/packages/compiler-cli/src/ngtsc/imports/src/core.ts @@ -52,6 +52,7 @@ export class NoopImportRewriter implements ImportRewriter { /** * A mapping of supported symbols that can be imported from within @angular/core, and the names by * which they're exported from r3_symbols. + * */ const CORE_SUPPORTED_SYMBOLS = new Map([ ['ɵɵdefineInjectable', 'ɵɵdefineInjectable'], @@ -74,6 +75,7 @@ const CORE_MODULE = '@angular/core'; /** * `ImportRewriter` that rewrites imports from '@angular/core' to be imported from the r3_symbols.ts * file instead. + * */ export class R3SymbolsImportRewriter implements ImportRewriter { constructor(private r3SymbolsPath: string) {} diff --git a/packages/compiler-cli/src/ngtsc/imports/src/default.ts b/packages/compiler-cli/src/ngtsc/imports/src/default.ts index bf275816eeb..3872c5c20b0 100644 --- a/packages/compiler-cli/src/ngtsc/imports/src/default.ts +++ b/packages/compiler-cli/src/ngtsc/imports/src/default.ts @@ -65,7 +65,8 @@ export function getDefaultImportDeclaration(expr: WrappedNodeExpr): ts. * required. * * This problem does not exist for non-default imports as the compiler can easily insert - * "import * as X" style imports for those, and the "X" identifier survives transformation. + * "import \* as X" style imports for those, and the "X" identifier survives transformation. + * */ export class DefaultImportTracker { /** diff --git a/packages/compiler-cli/src/ngtsc/imports/src/patch_alias_reference_resolution.ts b/packages/compiler-cli/src/ngtsc/imports/src/patch_alias_reference_resolution.ts index c78e045f678..6ddff442a4f 100644 --- a/packages/compiler-cli/src/ngtsc/imports/src/patch_alias_reference_resolution.ts +++ b/packages/compiler-cli/src/ngtsc/imports/src/patch_alias_reference_resolution.ts @@ -54,9 +54,10 @@ interface EmitResolver { * because they are actually referenced (as they will now appear in static properties). * * More information about these limitations with transformers can be found in: - * 1. https://github.com/Microsoft/TypeScript/issues/17552. - * 2. https://github.com/microsoft/TypeScript/issues/17516. - * 3. https://github.com/angular/tsickle/issues/635. + * + * 1. https://github.com/Microsoft/TypeScript/issues/17552. + * 1. https://github.com/microsoft/TypeScript/issues/17516. + * 1. https://github.com/angular/tsickle/issues/635. * * The patch we apply to tell TypeScript about actual referenced aliases (i.e. imported symbols), * matches conceptually with the logic that runs internally in TypeScript when the @@ -69,7 +70,8 @@ interface EmitResolver { * * See below. Note that this uses sourcegraph as the TypeScript checker file doesn't display on * Github. - * https://sourcegraph.com/github.com/microsoft/TypeScript@3eaa7c65f6f076a08a5f7f1946fd0df7c7430259/-/blob/src/compiler/checker.ts#L31219-31257 + * [https://sourcegraph.com/github.com/microsoft/TypeScript@3eaa7c65f6f076a08a5f7f1946fd0df7c7430259/-/blob/src/compiler/checker.ts#L31219-31257](https://sourcegraph.com/github.com/microsoft/TypeScript@3eaa7c65f6f076a08a5f7f1946fd0df7c7430259/-/blob/src/compiler/checker.ts#L31219-31257) + * */ export function loadIsReferencedAliasDeclarationPatch(context: ts.TransformationContext): Set { diff --git a/packages/compiler-cli/src/ngtsc/partial_evaluator/src/result.ts b/packages/compiler-cli/src/ngtsc/partial_evaluator/src/result.ts index 5dcddea8d3b..aa65ce82974 100644 --- a/packages/compiler-cli/src/ngtsc/partial_evaluator/src/result.ts +++ b/packages/compiler-cli/src/ngtsc/partial_evaluator/src/result.ts @@ -30,7 +30,8 @@ export type ResolvedValue = * An array of `ResolvedValue`s. * * This is a reified type to allow the circular reference of `ResolvedValue` -> `ResolvedValueArray` - * -> `ResolvedValue`. + * \-> `ResolvedValue`. + * */ export interface ResolvedValueArray extends Array {} @@ -38,7 +39,8 @@ export interface ResolvedValueArray extends Array {} * A map of strings to `ResolvedValue`s. * * This is a reified type to allow the circular reference of `ResolvedValue` -> `ResolvedValueMap` - * -> `ResolvedValue`. + * \-> `ResolvedValue`. + * */ export interface ResolvedValueMap extends Map {} diff --git a/packages/compiler-cli/src/ngtsc/reflection/src/host.ts b/packages/compiler-cli/src/ngtsc/reflection/src/host.ts index 0df73eb6f12..ff9d51dc417 100644 --- a/packages/compiler-cli/src/ngtsc/reflection/src/host.ts +++ b/packages/compiler-cli/src/ngtsc/reflection/src/host.ts @@ -65,6 +65,7 @@ export function isDecoratorIdentifier(exp: ts.Expression): exp is DecoratorIdent * The `ts.Declaration` of a "class". * * Classes are represented differently in different code formats: + * * - In TS code, they are typically defined using the `class` keyword. * - In ES2015 code, they are usually defined using the `class` keyword, but they can also be * variable declarations, which are initialized to a class expression (e.g. @@ -75,6 +76,7 @@ export function isDecoratorIdentifier(exp: ts.Expression): exp is DecoratorIdent * * For `ReflectionHost` purposes, a class declaration should always have a `name` identifier, * because we need to be able to reference it in other parts of the program. + * */ export type ClassDeclaration = T&{name: ts.Identifier}; @@ -465,6 +467,7 @@ export interface Import { * The module from which the symbol was imported. * * This could either be an absolute module name (@angular/core for example) or a relative path. + * */ from: string; diff --git a/packages/compiler-cli/src/ngtsc/reflection/src/typescript.ts b/packages/compiler-cli/src/ngtsc/reflection/src/typescript.ts index 8e9d12b892d..e9c40136457 100644 --- a/packages/compiler-cli/src/ngtsc/reflection/src/typescript.ts +++ b/packages/compiler-cli/src/ngtsc/reflection/src/typescript.ts @@ -689,12 +689,13 @@ const LocalExportedDeclarations = Symbol('LocalExportedDeclarations'); * * This cache does not cause memory leaks as: * - * 1. The only references cached here are local to the `ts.SourceFile`, and thus also available in - * `this.statements`. + * 1. The only references cached here are local to the `ts.SourceFile`, and thus also available in + * `this.statements`. + * + * 1. The only way this `Set` could change is if the source file itself was changed, which would + * invalidate the entire `ts.SourceFile` object in favor of a new version. Thus, changing the + * source file also invalidates this cache. * - * 2. The only way this `Set` could change is if the source file itself was changed, which would - * invalidate the entire `ts.SourceFile` object in favor of a new version. Thus, changing the - * source file also invalidates this cache. */ interface SourceFileWithCachedExports extends ts.SourceFile { /** diff --git a/packages/compiler-cli/src/ngtsc/transform/src/transform.ts b/packages/compiler-cli/src/ngtsc/transform/src/transform.ts index aa652227a6b..0b30f0852b9 100644 --- a/packages/compiler-cli/src/ngtsc/transform/src/transform.ts +++ b/packages/compiler-cli/src/ngtsc/transform/src/transform.ts @@ -26,6 +26,7 @@ const CLOSURE_FILE_OVERVIEW_REGEXP = /\s+@fileoverview\s+/i; /** * Metadata to support @fileoverview blocks (Closure annotations) extracting/restoring. + * */ interface FileOverviewMeta { comments: ts.SynthesizedComment[]; diff --git a/packages/compiler-cli/src/ngtsc/translator/src/api/ast_factory.ts b/packages/compiler-cli/src/ngtsc/translator/src/api/ast_factory.ts index a5c2a602b6c..355c7159abb 100644 --- a/packages/compiler-cli/src/ngtsc/translator/src/api/ast_factory.ts +++ b/packages/compiler-cli/src/ngtsc/translator/src/api/ast_factory.ts @@ -10,8 +10,9 @@ * Used to create transpiler specific AST nodes from Angular Output AST nodes in an abstract way. * * Note that the `AstFactory` makes no assumptions about the target language being generated. - * It is up to the caller to do this - e.g. only call `createTaggedTemplate()` or pass `let`|`const` + * It is up to the caller to do this - e.g. only call `createTaggedTemplate()` or pass `let`\|`const` * to `createVariableDeclaration()` if the final JS will allow it. + * */ export interface AstFactory { /** diff --git a/packages/compiler-cli/src/ngtsc/tsc_plugin.ts b/packages/compiler-cli/src/ngtsc/tsc_plugin.ts index a7f70bc4833..ce1bb78b889 100644 --- a/packages/compiler-cli/src/ngtsc/tsc_plugin.ts +++ b/packages/compiler-cli/src/ngtsc/tsc_plugin.ts @@ -27,6 +27,7 @@ import {OptimizeFor} from './typecheck/api'; * * Currently mirrored from @bazel/concatjs/internal/tsc_wrapped/plugin_api (with the naming of * `fileNameToModuleName` corrected). + * */ export interface PluginCompilerHost extends ts.CompilerHost, Partial { readonly inputFiles: ReadonlyArray; diff --git a/packages/compiler-cli/src/ngtsc/typecheck/api/checker.ts b/packages/compiler-cli/src/ngtsc/typecheck/api/checker.ts index 10d0f60c682..632a8fe0a44 100644 --- a/packages/compiler-cli/src/ngtsc/typecheck/api/checker.ts +++ b/packages/compiler-cli/src/ngtsc/typecheck/api/checker.ts @@ -27,11 +27,13 @@ import {ElementSymbol, Symbol, TcbLocation, TemplateSymbol} from './symbols'; * This interface is analogous to TypeScript's own `ts.TypeChecker` API. * * In general, this interface supports two kinds of operations: - * - updating Type Check Blocks (TCB)s that capture the template in the form of TypeScript code - * - querying information about available TCBs, including diagnostics + * + * - updating Type Check Blocks (TCB)s that capture the template in the form of TypeScript code + * - querying information about available TCBs, including diagnostics * * Once a TCB is available, information about it can be queried. If no TCB is available to answer a * query, depending on the method either `null` will be returned or an error will be thrown. + * */ export interface TemplateTypeChecker { /** @@ -106,9 +108,10 @@ export interface TemplateTypeChecker { * * Global completions are completions in the global context, as opposed to completions within an * existing expression. For example, completing inside a new interpolation expression (`{{|}}`) or - * inside a new property binding `[input]="|" should retrieve global completions, which will + * inside a new property binding \`[input]="|" should retrieve global completions, which will * include completions from the template's context component, as well as any local references or * template variables which are in scope for that expression. + * */ getGlobalCompletions( context: TmplAstTemplate|null, component: ts.ClassDeclaration, @@ -159,6 +162,7 @@ export interface TemplateTypeChecker { /** * Get the primary decorator for an Angular class (such as @Component). This does not work for * `@Injectable`. + * */ getPrimaryAngularDecorator(target: ts.ClassDeclaration): ts.Decorator|null; diff --git a/packages/compiler-cli/src/ngtsc/typecheck/api/completion.ts b/packages/compiler-cli/src/ngtsc/typecheck/api/completion.ts index 65e4e533204..9b39fd13dcd 100644 --- a/packages/compiler-cli/src/ngtsc/typecheck/api/completion.ts +++ b/packages/compiler-cli/src/ngtsc/typecheck/api/completion.ts @@ -52,8 +52,10 @@ export interface VariableCompletion { * Autocompletion data for an expression in the global scope. * * Global completion is accomplished by merging data from two sources: - * * TypeScript completion of the component's class members. - * * Local references and variables that are in scope at a given template level. + * + * - TypeScript completion of the component's class members. + * - Local references and variables that are in scope at a given template level. + * */ export interface GlobalCompletion { /** diff --git a/packages/compiler-cli/src/ngtsc/typecheck/api/symbols.ts b/packages/compiler-cli/src/ngtsc/typecheck/api/symbols.ts index 4384a46be3a..bd14071a07b 100644 --- a/packages/compiler-cli/src/ngtsc/typecheck/api/symbols.ts +++ b/packages/compiler-cli/src/ngtsc/typecheck/api/symbols.ts @@ -158,9 +158,11 @@ export interface ReferenceSymbol { /** * Depending on the type of the reference, this is one of the following: - * - `TmplAstElement` when the local ref refers to the HTML element - * - `TmplAstTemplate` when the ref refers to an `ng-template` - * - `ts.ClassDeclaration` when the local ref refers to a Directive instance (#ref="myExportAs") + * + * - `TmplAstElement` when the local ref refers to the HTML element + * - `TmplAstTemplate` when the ref refers to an `ng-template` + * - `ts.ClassDeclaration` when the local ref refers to a Directive instance (#ref="myExportAs") + * */ target: TmplAstElement|TmplAstTemplate|ts.ClassDeclaration; @@ -173,11 +175,14 @@ export interface ReferenceSymbol { /** * The location in the shim file of a variable that holds the type of the local ref. * For example, a reference declaration like the following: + * * ``` * var _t1 = document.createElement('div'); * var _t2 = _t1; // This is the reference declaration * ``` + * * This `targetLocation` is `[_t1 variable declaration].getStart()`. + * */ targetLocation: TcbLocation; @@ -313,7 +318,10 @@ export interface PipeSymbol { classSymbol: ClassSymbol; } -/** Represents an instance of a class found in the TCB, i.e. `var _pipe1: MyPipe = null!; */ +/** + * Represents an instance of a class found in the TCB, i.e. \`var \_pipe1: MyPipe = null!; + * + */ export interface ClassSymbol { /** The `ts.Type` of class. */ tsType: ts.Type; diff --git a/packages/compiler-cli/src/ngtsc/typecheck/extended/checks/invalid_banana_in_box/index.ts b/packages/compiler-cli/src/ngtsc/typecheck/extended/checks/invalid_banana_in_box/index.ts index aee972012af..6e33cbfae90 100644 --- a/packages/compiler-cli/src/ngtsc/typecheck/extended/checks/invalid_banana_in_box/index.ts +++ b/packages/compiler-cli/src/ngtsc/typecheck/extended/checks/invalid_banana_in_box/index.ts @@ -16,7 +16,8 @@ import {TemplateCheckFactory, TemplateCheckWithVisitor, TemplateContext} from '. /** * Ensures the two-way binding syntax is correct. * Parentheses should be inside the brackets "[()]". - * Will return diagnostic information when "([])" is found. + * Will return diagnostic information when "(\[])" is found. + * */ class InvalidBananaInBoxCheck extends TemplateCheckWithVisitor { override code = ErrorCode.INVALID_BANANA_IN_BOX as const; diff --git a/packages/compiler-cli/src/ngtsc/typecheck/src/environment.ts b/packages/compiler-cli/src/ngtsc/typecheck/src/environment.ts index edd234dfaa2..3d0572b5aa4 100644 --- a/packages/compiler-cli/src/ngtsc/typecheck/src/environment.ts +++ b/packages/compiler-cli/src/ngtsc/typecheck/src/environment.ts @@ -25,10 +25,11 @@ import {TypeParameterEmitter} from './type_parameter_emitter'; * An `Environment` supports the generation of TCBs by tracking necessary imports, declarations of * type constructors, and other statements beyond the type-checking code within the TCB itself. * Through method calls on `Environment`, the TCB generator can request `ts.Expression`s which - * reference declarations in the `Environment` for these artifacts`. + * reference declarations in the `Environment` for these artifacts\`. * * `Environment` can be used in a standalone fashion, or can be extended to support more specialized * usage. + * */ export class Environment implements ReferenceEmitEnvironment { private nextIds = { diff --git a/packages/compiler-cli/src/ngtsc/typecheck/src/type_check_block.ts b/packages/compiler-cli/src/ngtsc/typecheck/src/type_check_block.ts index e7ccf1518d1..ed875341072 100644 --- a/packages/compiler-cli/src/ngtsc/typecheck/src/type_check_block.ts +++ b/packages/compiler-cli/src/ngtsc/typecheck/src/type_check_block.ts @@ -520,11 +520,13 @@ class TcbGenericDirectiveTypeWithAnyParamsOp extends TcbDirectiveTypeOpBase { * The initializer for the variable is the variable expression for the directive, template, or * element the ref refers to. When the reference is used in the template, those TCB statements will * access this variable as well. For example: + * * ``` * var _t1 = document.createElement('div'); * var _t2 = _t1; * _t2.value * ``` + * * This operation supports more fluent lookups for the `TemplateTypeChecker` when getting a symbol * for a reference. In most cases, this isn't essential; that is, the information for the symbol * could be gathered without this operation using the `BoundTarget`. However, for the case of @@ -534,6 +536,7 @@ class TcbGenericDirectiveTypeWithAnyParamsOp extends TcbDirectiveTypeOpBase { * * Executing this operation returns a reference to the directive instance variable with its inferred * type. + * */ class TcbReferenceOp extends TcbOp { constructor( diff --git a/packages/compiler-cli/src/ngtsc/typecheck/src/type_constructor.ts b/packages/compiler-cli/src/ngtsc/typecheck/src/type_constructor.ts index 4e92ededbe6..be07380f21f 100644 --- a/packages/compiler-cli/src/ngtsc/typecheck/src/type_constructor.ts +++ b/packages/compiler-cli/src/ngtsc/typecheck/src/type_constructor.ts @@ -64,7 +64,7 @@ export function generateTypeCtorDeclarationFn( * * An inline type constructor for NgFor looks like: * - * static ngTypeCtor(init: Pick, 'ngForOf'|'ngForTrackBy'|'ngForTemplate'>): + * static ngTypeCtor(init: Pick<NgForOf, 'ngForOf'|'ngForTrackBy'|'ngForTemplate'>): * NgForOf; * * A typical constructor would be: diff --git a/packages/compiler-cli/src/transformers/api.ts b/packages/compiler-cli/src/transformers/api.ts index 4f248213feb..c89a6ccc293 100644 --- a/packages/compiler-cli/src/transformers/api.ts +++ b/packages/compiler-cli/src/transformers/api.ts @@ -95,6 +95,7 @@ export interface CompilerOptions extends NgCompilerOptions, ts.CompilerOptions { * order to avoid dynamically generated module dependencies which can break strict * dependency enforcements. This is not enabled by default. * Read more about this here: https://github.com/angular/angular/issues/25644. + * */ createExternalSymbolFactoryReexports?: boolean; } diff --git a/packages/compiler-cli/src/transformers/downlevel_decorators_transform/downlevel_decorators_transform.ts b/packages/compiler-cli/src/transformers/downlevel_decorators_transform/downlevel_decorators_transform.ts index 73480a2725a..57c07b907ac 100644 --- a/packages/compiler-cli/src/transformers/downlevel_decorators_transform/downlevel_decorators_transform.ts +++ b/packages/compiler-cli/src/transformers/downlevel_decorators_transform/downlevel_decorators_transform.ts @@ -14,6 +14,7 @@ import {Decorator, ReflectionHost} from '../../ngtsc/reflection'; /** * Whether a given decorator should be treated as an Angular decorator. * Either it's used in @angular/core, or it's imported from there. + * */ function isAngularDecorator(decorator: Decorator, isCore: boolean): boolean { return isCore || (decorator.import !== null && decorator.import.from === '@angular/core'); @@ -49,6 +50,7 @@ const DECORATOR_INVOCATION_JSDOC_TYPE = '!Array<{type: !Function, args: (undefin * * // For @decorator(arg1, arg2) * { type: decorator, args: [arg1, arg2] } + * */ function extractMetadataFromSingleDecorator( decorator: ts.Decorator, diagnostics: ts.Diagnostic[]): ts.ObjectLiteralExpression { @@ -93,13 +95,14 @@ function extractMetadataFromSingleDecorator( * downleveled decorator information. * * The property contains an arrow function that returns an array of object literals of the shape: - * static ctorParameters = () => [{ + * static ctorParameters = () => \[{ * type: SomeClass|undefined, // the type of the param that's decorated, if it's a value. - * decorators: [{ + * decorators: \[{ * type: DecoratorFn, // the type of the decorator that's invoked. * args: [ARGS], // the arguments passed to the decorator. * }] * }]; + * */ function createCtorParametersClassProperty( diagnostics: ts.Diagnostic[], @@ -217,8 +220,9 @@ function typeReferenceToExpression( * Checks whether a given symbol refers to a value that exists at runtime (as distinct from a type). * * Expands aliases, which is important for the case where - * import * as x from 'some-module'; + * import \* as x from 'some-module'; * and x is now a value (the module object). + * */ function symbolIsRuntimeValue(typeChecker: ts.TypeChecker, symbol: ts.Symbol): boolean { if (symbol.flags & ts.SymbolFlags.Alias) { @@ -277,10 +281,11 @@ export function getDownlevelDecoratorsTransform( * property containing type information for every property that has a * decorator applied. * - * static propDecorators: {[key: string]: {type: Function, args?: - * any[]}[]} = { propA: [{type: MyDecorator, args: [1, 2]}, ...], + * static propDecorators: {[key: string]: {type: Function, args?: + * any\[]}\[]} = { propA: \[{type: MyDecorator, args: [1, 2]}, ...], * ... * }; + * */ function createPropDecoratorsClassProperty( diagnostics: ts.Diagnostic[], @@ -464,10 +469,12 @@ export function getDownlevelDecoratorsTransform( /** * Transforms a single class declaration: + * * - dispatches to strip decorators on members * - converts decorators on the class to annotations * - creates a ctorParameters property * - creates a propDecorators property + * */ function transformClassDeclaration(classDecl: ts.ClassDeclaration): ts.ClassDeclaration { const newMembers: ts.ClassElement[] = []; diff --git a/packages/compiler-cli/src/transformers/program.ts b/packages/compiler-cli/src/transformers/program.ts index b4c838c4519..a0db8c5c81c 100644 --- a/packages/compiler-cli/src/transformers/program.ts +++ b/packages/compiler-cli/src/transformers/program.ts @@ -1,4 +1,3 @@ - /** * @license * Copyright Google LLC All Rights Reserved. diff --git a/packages/compiler-cli/src/typescript_support.ts b/packages/compiler-cli/src/typescript_support.ts index 6df2ecec9c1..c5487769dc6 100644 --- a/packages/compiler-cli/src/typescript_support.ts +++ b/packages/compiler-cli/src/typescript_support.ts @@ -20,11 +20,12 @@ const MIN_TS_VERSION = '5.2.0'; /** * Supremum of supported TypeScript versions - * ∀ supported typescript version v, v < MAX_TS_VERSION + * ∀ supported typescript version v, v < MAX_TS_VERSION * MAX_TS_VERSION is not considered as a supported TypeScript version * * Note: this check is disabled in g3, search for * `angularCompilerOptions.disableTypeScriptVersionCheck` config param value in g3. + * */ const MAX_TS_VERSION = '5.4.0'; @@ -43,15 +44,15 @@ export function restoreTypeScriptVersionForTesting(): void { } /** - * Checks whether a given version ∈ [minVersion, maxVersion[. - * An error will be thrown when the given version ∉ [minVersion, maxVersion[. + * Checks whether a given version ∈ \[minVersion, maxVersion\[. + * An error will be thrown when the given version ∉ \[minVersion, maxVersion\[. * * @param version The version on which the check will be performed * @param minVersion The lower bound version. A valid version needs to be greater than minVersion * @param maxVersion The upper bound version. A valid version needs to be strictly less than * maxVersion + * @throws Will throw an error if the given version ∉ \[minVersion, maxVersion\[ * - * @throws Will throw an error if the given version ∉ [minVersion, maxVersion[ */ export function checkVersion(version: string, minVersion: string, maxVersion: string) { if ((compareVersions(version, minVersion) < 0 || compareVersions(version, maxVersion) >= 0)) { diff --git a/packages/compiler-cli/src/version_helpers.ts b/packages/compiler-cli/src/version_helpers.ts index 6f5fcdc9423..dbdb02709be 100644 --- a/packages/compiler-cli/src/version_helpers.ts +++ b/packages/compiler-cli/src/version_helpers.ts @@ -29,7 +29,7 @@ export function toNumbers(value: string): number[] { * Compares two arrays of positive numbers with lexicographical order in mind. * * However - unlike lexicographical order - for arrays of different length we consider: - * [1, 2, 3] = [1, 2, 3, 0] instead of [1, 2, 3] < [1, 2, 3, 0] + * [1, 2, 3] = [1, 2, 3, 0] instead of [1, 2, 3] < [1, 2, 3, 0] * * @param a The 'left hand' array in the comparison test * @param b The 'right hand' in the comparison test @@ -66,6 +66,7 @@ export function compareNumbers(a: number[], b: number[]): -1|0|1 { /** * Checks if a TypeScript version is: + * * - greater or equal than the provided `low` version, * - lower or equal than an optional `high` version. * diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/module_optimization.ts b/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/module_optimization.ts index da8d7ccfd81..df2c13dbfea 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/module_optimization.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/components_and_directives/standalone/module_optimization.ts @@ -16,4 +16,4 @@ export class StandaloneDir { imports: [StandaloneCmp, StandaloneDir], }) export class Module { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/ng_modules/forward_refs.ts b/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/ng_modules/forward_refs.ts index 1a05a3d5b5c..747449b4a80 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/ng_modules/forward_refs.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_compiler_compliance/ng_modules/forward_refs.ts @@ -10,4 +10,4 @@ export class TestModule { @NgModule() export class ForwardModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler/interpolations/test.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler/interpolations/test.ts index 8d66fbda08e..e71378d2d8d 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler/interpolations/test.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler/interpolations/test.ts @@ -11,4 +11,4 @@ export class MyApp { @NgModule({declarations: [MyApp]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_di/di/providedin_forwardref.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_di/di/providedin_forwardref.ts index 03669fca444..60bbec5847e 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_di/di/providedin_forwardref.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_di/di/providedin_forwardref.ts @@ -9,4 +9,4 @@ export class Service { } @NgModule() export class Mod { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/empty_attributes.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/empty_attributes.ts index 02a680aa1e7..014862f8e13 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/empty_attributes.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/empty_attributes.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/i18n_root_node.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/i18n_root_node.ts index dd4272089f5..e5392443935 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/i18n_root_node.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/i18n_root_node.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/invalid_i18n_meta.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/invalid_i18n_meta.ts index a0cf318d860..78ea790ac74 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/invalid_i18n_meta.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/invalid_i18n_meta.ts @@ -13,4 +13,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/meaning_description.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/meaning_description.ts index 1566e9d7982..f5875de5116 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/meaning_description.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/meaning_description.ts @@ -18,4 +18,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/ng-template_basic.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/ng-template_basic.ts index 6cf8b93dac5..095a3e6673e 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/ng-template_basic.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/ng-template_basic.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes.ts index ef28844c12a..48bc2adb7f6 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes_structural.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes_structural.ts index a0adbb98c74..f08704247ff 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes_structural.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/element_attributes/static_attributes_structural.ts @@ -12,4 +12,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/es5_support/test.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/es5_support/test.ts index 6fa5159e311..0159caa1c31 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/es5_support/test.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/es5_support/test.ts @@ -9,4 +9,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/localize_legacy_message_ids/legacy_disabled.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/localize_legacy_message_ids/legacy_disabled.ts index 014baabeee6..5636e6a9fae 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/localize_legacy_message_ids/legacy_disabled.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/localize_legacy_message_ids/legacy_disabled.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/foreign_object.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/foreign_object.ts index 15ce810329c..21be559ec04 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/foreign_object.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/foreign_object.ts @@ -17,4 +17,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/namespaced_div.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/namespaced_div.ts index 2b8d51a865d..6ab8b368256 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/namespaced_div.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/namespaces/namespaced_div.ts @@ -17,4 +17,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/comments_in_translated_text.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/comments_in_translated_text.ts index e38ed1f1563..fc54bd8192a 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/comments_in_translated_text.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/comments_in_translated_text.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/directives.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/directives.ts index 5039e13dc6b..46d08793ced 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/directives.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/directives.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/empty_content.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/empty_content.ts index 82470512df4..19fd1ef52bd 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/empty_content.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/empty_content.ts @@ -15,4 +15,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/escape_quotes.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/escape_quotes.ts index 9fc9b767308..51e60da2fc1 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/escape_quotes.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/escape_quotes.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates.ts index 4346db67231..7614bc12b00 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates.ts @@ -21,4 +21,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates_context.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates_context.ts index 2522a66b19a..9abecdd2722 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates_context.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/nested_templates_context.ts @@ -31,4 +31,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/plain_text_messages.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/plain_text_messages.ts index aaa3272f22f..ec1ef74041f 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/plain_text_messages.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/plain_text_messages.ts @@ -15,4 +15,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/self_closing.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/self_closing.ts index fc454da0d0c..4a70ac3243b 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/self_closing.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/nested_nodes/self_closing.ts @@ -13,4 +13,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/duplicate_content.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/duplicate_content.ts index 9a86dcf7373..b42221a0e37 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/duplicate_content.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/duplicate_content.ts @@ -12,4 +12,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_ng-container_const.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_ng-container_const.ts index bd67fbe80cb..50042a9ff9f 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_ng-container_const.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_ng-container_const.ts @@ -16,4 +16,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_templates.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_templates.ts index 81691f96855..b767dc94e87 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_templates.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/nested_templates.ts @@ -21,4 +21,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/ng-container_with_non_text_content.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/ng-container_with_non_text_content.ts index efbc996f0d0..73de320d7db 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/ng-container_with_non_text_content.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/ng-container_with_non_text_content.ts @@ -13,4 +13,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_ng-container.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_ng-container.ts index c7f684a4e48..ad85689e13d 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_ng-container.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_ng-container.ts @@ -13,4 +13,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_tags.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_tags.ts index d9566524907..7da7ad023b2 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_tags.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/self_closing_tags.ts @@ -16,4 +16,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/single_ng-template.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/single_ng-template.ts index dcb4f249884..dfb737d4751 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/single_ng-template.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/single_ng-template.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/structural_directives.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/structural_directives.ts index 2a49e48c674..3a3ef5aeab9 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/structural_directives.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/ng-container_ng-template/structural_directives.ts @@ -12,4 +12,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/ng-container_ng-template.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/ng-container_ng-template.ts index d9bec7fa83b..b6382ee7e88 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/ng-container_ng-template.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/ng-container_ng-template.ts @@ -12,4 +12,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/styles.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/styles.ts index eb0502df5b9..21b24474044 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/styles.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/styles.ts @@ -12,4 +12,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/text_only_content.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/text_only_content.ts index 277139ce04c..2fd7796aa7b 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/text_only_content.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/self-closing_i18n_instructions/text_only_content.ts @@ -11,4 +11,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/whitespace_preserving_mode/preserve_inner_content.ts b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/whitespace_preserving_mode/preserve_inner_content.ts index 89028fd734c..acce5a27c1d 100644 --- a/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/whitespace_preserving_mode/preserve_inner_content.ts +++ b/packages/compiler-cli/test/compliance/test_cases/r3_view_compiler_i18n/whitespace_preserving_mode/preserve_inner_content.ts @@ -15,4 +15,4 @@ export class MyComponent { @NgModule({declarations: [MyComponent]}) export class MyModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_cases/source_mapping/inline_templates/interpolation_with_pipe.ts b/packages/compiler-cli/test/compliance/test_cases/source_mapping/inline_templates/interpolation_with_pipe.ts index 090591a54cc..867cd4deb87 100644 --- a/packages/compiler-cli/test/compliance/test_cases/source_mapping/inline_templates/interpolation_with_pipe.ts +++ b/packages/compiler-cli/test/compliance/test_cases/source_mapping/inline_templates/interpolation_with_pipe.ts @@ -14,4 +14,4 @@ export class PercentPipe implements PipeTransform { @NgModule({declarations: [TestCmp, PercentPipe]}) export class AppModule { -} \ No newline at end of file +} diff --git a/packages/compiler-cli/test/compliance/test_helpers/compile_test.ts b/packages/compiler-cli/test/compliance/test_helpers/compile_test.ts index c32308ddf8a..40bd1addf3d 100644 --- a/packages/compiler-cli/test/compliance/test_helpers/compile_test.ts +++ b/packages/compiler-cli/test/compliance/test_helpers/compile_test.ts @@ -123,10 +123,11 @@ function getOptions( } /** - * Replace escaped line-ending markers (\r\n) with real line-ending characters. + * Replace escaped line-ending markers (\\r\\n) with real line-ending characters. * * This allows us to simulate, more reliably, files that have `\r\n` line-endings. * (See `test_cases/r3_view_compiler_i18n/line_ending_normalization/template.html`.) + * */ function monkeyPatchReadFile(fs: ReadonlyFileSystem): void { const originalReadFile = fs.readFile; diff --git a/packages/compiler-cli/test/compliance/test_helpers/get_compliance_tests.ts b/packages/compiler-cli/test/compliance/test_helpers/get_compliance_tests.ts index 0bb3c55570c..895ce9d2be7 100644 --- a/packages/compiler-cli/test/compliance/test_helpers/get_compliance_tests.ts +++ b/packages/compiler-cli/test/compliance/test_helpers/get_compliance_tests.ts @@ -249,9 +249,15 @@ export interface ComplianceTest { skipForTemplatePipeline?: boolean; /** If set to `true`, this test will only execute when the template pipeline is used. */ onlyForTemplatePipeline?: boolean; - /** If set to `true`, then focus on this test (equivalent to jasmine's 'fit()`). */ + /** + * If set to `true`, then focus on this test (equivalent to jasmine's 'fit()\`). + * + */ focusTest?: boolean; - /** If set to `true`, then exclude this test (equivalent to jasmine's 'xit()`). */ + /** + * If set to `true`, then exclude this test (equivalent to jasmine's 'xit()\`). + * + */ excludeTest?: boolean; } diff --git a/packages/compiler/src/compiler_facade_interface.ts b/packages/compiler/src/compiler_facade_interface.ts index cf40af67d07..37f33d5b00b 100644 --- a/packages/compiler/src/compiler_facade_interface.ts +++ b/packages/compiler/src/compiler_facade_interface.ts @@ -11,14 +11,17 @@ * for late binding of `@angular/compiler` for JIT purposes. * * This file has two copies. Please ensure that they are in sync: - * - packages/compiler/src/compiler_facade_interface.ts (main) - * - packages/core/src/compiler/compiler_facade_interface.ts (replica) + * + * - packages/compiler/src/compiler_facade_interface.ts (main) + * - packages/core/src/compiler/compiler_facade_interface.ts (replica) * * Please ensure that the two files are in sync using this command: + * * ``` * cp packages/compiler/src/compiler_facade_interface.ts \ * packages/core/src/compiler/compiler_facade_interface.ts * ``` + * */ export interface ExportedCompilerFacade { diff --git a/packages/compiler/src/core.ts b/packages/compiler/src/core.ts index 3ed08b968d7..214146c6ef6 100644 --- a/packages/compiler/src/core.ts +++ b/packages/compiler/src/core.ts @@ -202,17 +202,21 @@ export const enum AttributeMarker { * Signals class declaration. * * Each value following `Classes` designates a class name to include on the element. + * * ## Example: * * Given: + * * ``` *
    ... * ``` * * the generated code is: + * * ``` * var _c1 = [AttributeMarker.Classes, 'foo', 'bar', 'baz']; * ``` + * */ Classes = 1, @@ -221,17 +225,21 @@ export const enum AttributeMarker { * * Each pair of values following `Styles` designates a style name and value to include on the * element. + * * ## Example: * * Given: + * * ``` *
    ...
    * ``` * * the generated code is: + * * ``` * var _c1 = [AttributeMarker.Styles, 'width', '100px', 'height'. '200px', 'color', 'red']; * ``` + * */ Styles = 2, @@ -307,6 +315,8 @@ export const enum AttributeMarker { * * ``` * var _c1 = ['moo', 'car', AttributeMarker.I18n, 'foo', 'bar']; + * ``` + * */ I18n = 6, } diff --git a/packages/compiler/src/expression_parser/ast.ts b/packages/compiler/src/expression_parser/ast.ts index 937fe11fe37..4c476efc5a6 100644 --- a/packages/compiler/src/expression_parser/ast.ts +++ b/packages/compiler/src/expression_parser/ast.ts @@ -344,20 +344,21 @@ export class ASTWithSource extends AST { * TemplateBinding refers to a particular key-value pair in a microsyntax * expression. A few examples are: * - * |---------------------|--------------|---------|--------------| + * \|---------------------\|--------------\|---------\|--------------\| * | expression | key | value | binding type | - * |---------------------|--------------|---------|--------------| + * \|---------------------\|--------------\|---------\|--------------\| * | 1. let item | item | null | variable | * | 2. of items | ngForOf | items | expression | * | 3. let x = y | x | y | variable | * | 4. index as i | i | index | variable | * | 5. trackBy: func | ngForTrackBy | func | expression | - * | 6. *ngIf="cond" | ngIf | cond | expression | - * |---------------------|--------------|---------|--------------| + * | 6. \*ngIf="cond" | ngIf | cond | expression | + * \|---------------------\|--------------\|---------\|--------------\| * * (6) is a notable exception because it is a binding from the template key in * the LHS of a HTML attribute to the expression in the RHS. All other bindings * in the example above are derived solely from the RHS. + * */ export type TemplateBinding = VariableBinding|ExpressionBinding; @@ -379,9 +380,11 @@ export class ExpressionBinding { * @param key binding name, like ngForOf, ngForTrackBy, ngIf, along with its * span. Note that the length of the span may not be the same as * `key.source.length`. For example, + * * 1. key.source = ngFor, key.span is for "ngFor" * 2. key.source = ngForOf, key.span is for "of" * 3. key.source = ngForTrackBy, key.span is for "trackBy" + * * @param value optional expression for the RHS. */ constructor( diff --git a/packages/compiler/src/expression_parser/parser.ts b/packages/compiler/src/expression_parser/parser.ts index a60c08efd84..504a3ab3e11 100644 --- a/packages/compiler/src/expression_parser/parser.ts +++ b/packages/compiler/src/expression_parser/parser.ts @@ -113,22 +113,26 @@ export class Parser { * parsing errors in case the given expression is invalid. * * For example, + * * ``` *
    * ^ ^ absoluteValueOffset for `templateValue` * absoluteKeyOffset for `templateKey` * ``` + * * contains three bindings: + * * 1. ngFor -> null * 2. item -> NgForOfContext.$implicit * 3. ngForOf -> items * * This is apparent from the de-sugared template: + * * ``` * * ``` * - * @param templateKey name of directive, without the * prefix. For example: ngIf, ngFor + * @param templateKey name of directive, without the \* prefix. For example: ngIf, ngFor * @param templateValue RHS of the microsyntax attribute * @param templateUrl template filename if it's external, component filename if it's inline * @param absoluteKeyOffset start of the `templateKey` @@ -1063,10 +1067,13 @@ export class _ParseAST { * parsing errors in case the given expression is invalid. * * For example, + * * ``` *
    * ``` + * * contains five bindings: + * * 1. ngFor -> null * 2. item -> NgForOfContext.$implicit * 3. ngForOf -> items @@ -1077,7 +1084,7 @@ export class _ParseAST { * https://gist.github.com/mhevery/d3530294cff2e4a1b3fe15ff75d08855 * * @param templateKey name of the microsyntax directive, like ngIf, ngFor, - * without the *, along with its absolute span. + * without the \*, along with its absolute span. */ parseTemplateBindings(templateKey: TemplateBindingIdentifier): TemplateBindingParseResult { const bindings: TemplateBinding[] = []; diff --git a/packages/compiler/src/i18n/extractor_merger.ts b/packages/compiler/src/i18n/extractor_merger.ts index 33f951c6696..3418290712b 100644 --- a/packages/compiler/src/i18n/extractor_merger.ts +++ b/packages/compiler/src/i18n/extractor_merger.ts @@ -50,6 +50,7 @@ enum _VisitorMode { /** * This Visitor is used: + * * 1. to extract all the translatable strings from an html AST (see `extract()`), * 2. to replace the translatable strings with the actual translations (see `merge()`) * diff --git a/packages/compiler/src/ml_parser/html_whitespaces.ts b/packages/compiler/src/ml_parser/html_whitespaces.ts index 3863ad078e7..1df962a734d 100644 --- a/packages/compiler/src/ml_parser/html_whitespaces.ts +++ b/packages/compiler/src/ml_parser/html_whitespaces.ts @@ -37,6 +37,7 @@ export function replaceNgsp(value: string): string { /** * This visitor can walk HTML parse tree and remove / trim text nodes using the following rules: + * * - consider spaces, tabs and new lines as whitespace characters; * - drop text nodes consisting of whitespace characters only; * - for all other text nodes replace consecutive whitespace characters with one space; @@ -48,6 +49,7 @@ export function replaceNgsp(value: string): string { * this visitor is not activated by default in Angular 5 and people need to explicitly opt-in for * whitespace removal. The default option for whitespace removal will be revisited in Angular 6 * and might be changed to "on" by default. + * */ export class WhitespaceVisitor implements html.Visitor { visitElement(element: html.Element, context: any): any { diff --git a/packages/compiler/src/ml_parser/lexer.ts b/packages/compiler/src/ml_parser/lexer.ts index 74ef678dea6..fb7e477f912 100644 --- a/packages/compiler/src/ml_parser/lexer.ts +++ b/packages/compiler/src/ml_parser/lexer.ts @@ -93,6 +93,7 @@ export interface TokenizeOptions { /** * Whether to tokenize @ block syntax. Otherwise considered text, * or ICU tokens if `tokenizeExpansionForms` is enabled. + * */ tokenizeBlocks?: boolean; } @@ -1044,9 +1045,10 @@ function mergeTextTokens(srcTokens: Token[]): Token[] { /** - * The _Tokenizer uses objects of this type to move through the input text, + * The \_Tokenizer uses objects of this type to move through the input text, * extracting "parsed characters". These could be more than one actual character * if the text contains escape sequences. + * */ interface CharacterCursor { /** Initialize the cursor. */ diff --git a/packages/compiler/src/output/abstract_js_emitter.ts b/packages/compiler/src/output/abstract_js_emitter.ts index de24fd080ce..1b8998065c3 100644 --- a/packages/compiler/src/output/abstract_js_emitter.ts +++ b/packages/compiler/src/output/abstract_js_emitter.ts @@ -16,11 +16,12 @@ import * as o from './output_ast'; * typically constructed with a function called `__makeTemplateObject(cooked, raw)`, but it may not * be available in all environments. * - * This is a JavaScript polyfill that uses __makeTemplateObject when it's available, but otherwise + * This is a JavaScript polyfill that uses \_\_makeTemplateObject when it's available, but otherwise * creates an inline helper with the same functionality. * * In the inline function, if `Object.defineProperty` is available we use that to attach the `raw` * array. + * */ const makeTemplateObjectPolyfill = '(this&&this.__makeTemplateObject||function(e,t){return Object.defineProperty?Object.defineProperty(e,"raw",{value:t}):e.raw=t,e})'; diff --git a/packages/compiler/src/output/output_ast.ts b/packages/compiler/src/output/output_ast.ts index b5ffd8a2dc2..34c4618751a 100644 --- a/packages/compiler/src/output/output_ast.ts +++ b/packages/compiler/src/output/output_ast.ts @@ -701,8 +701,9 @@ const escapeForTemplateLiteral = (str: string): string => * Creates a `{cooked, raw}` object from the `metaBlock` and `messagePart`. * * The `raw` text must have various character sequences escaped: - * * "\" would otherwise indicate that the next character is a control character. - * * "`" and "${" are template string control sequences that would otherwise prematurely indicate + * + * * "\\" would otherwise indicate that the next character is a control character. + * * "\`" and "${" are template string control sequences that would otherwise prematurely indicate * the end of a message part. * * ":" inside a metablock would prematurely indicate the end of the metablock. * * ":" at the start of a messagePart with no metablock would erroneously indicate the start of a diff --git a/packages/compiler/src/output/output_jit_trusted_types.ts b/packages/compiler/src/output/output_jit_trusted_types.ts index c89ce325d39..aeb1d3a1ca4 100644 --- a/packages/compiler/src/output/output_jit_trusted_types.ts +++ b/packages/compiler/src/output/output_jit_trusted_types.ts @@ -34,6 +34,7 @@ import {global} from '../util'; * Adapted from * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/trusted-types/index.d.ts * but restricted to the API surface used within Angular. + * */ export declare interface TrustedScript { diff --git a/packages/compiler/src/render3/partial/api.ts b/packages/compiler/src/render3/partial/api.ts index 82f125378c5..9976aca09b0 100644 --- a/packages/compiler/src/render3/partial/api.ts +++ b/packages/compiler/src/render3/partial/api.ts @@ -437,11 +437,13 @@ export enum FactoryTarget { export interface R3DeclareInjectableMetadata extends R3PartialDeclaration { /** * If provided, specifies that the declared injectable belongs to a particular injector: + * * - `InjectorType` such as `NgModule`, * - `'root'` the root injector * - `'any'` all injectors. - * If not provided, then it does not belong to any injector. Must be explicitly listed in the - * providers of an injector. + * If not provided, then it does not belong to any injector. Must be explicitly listed in the + * providers of an injector. + * */ providedIn?: o.Expression; @@ -497,24 +499,28 @@ export interface R3DeclareDependencyMetadata { /** * Whether the dependency has an @Host qualifier. * Default: false, + * */ host?: boolean; /** * Whether the dependency has an @Optional qualifier. * Default: false, + * */ optional?: boolean; /** * Whether the dependency has an @Self qualifier. * Default: false, + * */ self?: boolean; /** * Whether the dependency has an @SkipSelf qualifier. * Default: false, + * */ skipSelf?: boolean; } diff --git a/packages/compiler/src/render3/r3_class_metadata_compiler.ts b/packages/compiler/src/render3/r3_class_metadata_compiler.ts index 061df903286..01c0e7350e5 100644 --- a/packages/compiler/src/render3/r3_class_metadata_compiler.ts +++ b/packages/compiler/src/render3/r3_class_metadata_compiler.ts @@ -59,6 +59,7 @@ export function compileClassMetadata(metadata: R3ClassMetadata): o.Expression { * loads dependencies from `@defer` blocks. * * Generates a call like this: + * * ``` * setClassMetadataAsync(type, () => [ * import('./cmp-a').then(m => m.CmpA); @@ -70,6 +71,7 @@ export function compileClassMetadata(metadata: R3ClassMetadata): o.Expression { * * Similar to the `setClassMetadata` call, it's wrapped into the `ngDevMode` * check to tree-shake away this code in production mode. + * */ export function compileComponentClassMetadata( metadata: R3ClassMetadata, deferrableTypes: Map): o.Expression { diff --git a/packages/compiler/src/render3/r3_factory.ts b/packages/compiler/src/render3/r3_factory.ts index 3c311305d57..18a4b12d428 100644 --- a/packages/compiler/src/render3/r3_factory.ts +++ b/packages/compiler/src/render3/r3_factory.ts @@ -82,26 +82,31 @@ export interface R3DependencyMetadata { * If an @Attribute decorator is present, this is the literal type of the attribute name, or * the unknown type if no literal type is available (e.g. the attribute name is an expression). * Otherwise it is null; + * */ attributeNameType: o.Expression|null; /** * Whether the dependency has an @Host qualifier. + * */ host: boolean; /** * Whether the dependency has an @Optional qualifier. + * */ optional: boolean; /** * Whether the dependency has an @Self qualifier. + * */ self: boolean; /** * Whether the dependency has an @SkipSelf qualifier. + * */ skipSelf: boolean; } diff --git a/packages/compiler/src/render3/r3_jit.ts b/packages/compiler/src/render3/r3_jit.ts index 731aa1eb3ce..ebd20e3a130 100644 --- a/packages/compiler/src/render3/r3_jit.ts +++ b/packages/compiler/src/render3/r3_jit.ts @@ -14,6 +14,7 @@ import {ExternalReferenceResolver} from '../output/output_jit'; * symbols at runtime, according to a consumer-provided mapping. * * Only supports `resolveExternalReference`, all other methods throw. + * */ export class R3JitReflector implements ExternalReferenceResolver { constructor(private context: {[key: string]: unknown}) {} diff --git a/packages/compiler/src/render3/r3_module_compiler.ts b/packages/compiler/src/render3/r3_module_compiler.ts index a1485cb30dd..450288da5db 100644 --- a/packages/compiler/src/render3/r3_module_compiler.ts +++ b/packages/compiler/src/render3/r3_module_compiler.ts @@ -46,9 +46,11 @@ export enum R3SelectorScopeMode { /** * The type of the NgModule meta data. + * * - Global: Used for full and partial compilation modes which mainly includes R3References. * - Local: Used for the local compilation mode which mainly includes the raw expressions as appears - * in the NgModule decorator. + * in the NgModule decorator. + * */ export enum R3NgModuleMetadataKind { Global, diff --git a/packages/compiler/src/render3/view/api.ts b/packages/compiler/src/render3/view/api.ts index f2ca0d78ed0..ebf12429e37 100644 --- a/packages/compiler/src/render3/view/api.ts +++ b/packages/compiler/src/render3/view/api.ts @@ -156,15 +156,18 @@ export const enum DeclarationListEmitMode { * any forward references within the list are resolved when the outer closure is invoked. * * Consider the case where the runtime has captured two declarations in two distinct values: + * * ``` * const dirA = MyDir; * const dirB = forwardRef(function() { return ForwardRef; }); * ``` * * This mode would emit the declarations captured in `dirA` and `dirB` as follows: + * * ``` * directives: function () { return [dirA, dirB].map(ng.resolveForwardRef); }, * ``` + * */ ClosureResolved, @@ -260,10 +263,12 @@ export interface R3ComponentMetadata /** * 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; diff --git a/packages/compiler/src/render3/view/i18n/meta.ts b/packages/compiler/src/render3/view/i18n/meta.ts index 30c49435452..b5a5467ef30 100644 --- a/packages/compiler/src/render3/view/i18n/meta.ts +++ b/packages/compiler/src/render3/view/i18n/meta.ts @@ -43,8 +43,9 @@ const setI18nRefs: VisitNodeFn = (htmlNode, i18nNode) => { /** * This visitor walks over HTML parse tree and converts information stored in - * i18n-related attributes ("i18n" and "i18n-*") into i18n meta object that is + * i18n-related attributes ("i18n" and "i18n-\*") into i18n meta object that is * stored with other element's and attribute's information. + * */ export class I18nMetaVisitor implements html.Visitor { // whether visited nodes contain i18n information @@ -235,9 +236,11 @@ const I18N_ID_SEPARATOR = '@@'; /** * Parses i18n metas like: + * * - "@@id", * - "description[@@id]", * - "meaning|description[@@id]" + * * and returns an object with parsed output. * * @param meta String that represents i18n meta diff --git a/packages/compiler/src/render3/view/template.ts b/packages/compiler/src/render3/view/template.ts index 1a2093ae421..fbab9f053bf 100644 --- a/packages/compiler/src/render3/view/template.ts +++ b/packages/compiler/src/render3/view/template.ts @@ -2277,18 +2277,20 @@ type LocalVarRefCallback = (scope: BindingScope, retrievalLevel: number) => o.Ex const SHARED_CONTEXT_KEY = '$$shared_ctx$$'; /** - * This is used when one refers to variable such as: 'let abc = nextContext(2).$implicit`. + * This is used when one refers to variable such as: 'let abc = nextContext(2).$implicit\`. + * * - key to the map is the string literal `"abc"`. * - value `retrievalLevel` is the level from which this value can be retrieved, which is 2 levels - * up in example. + * up in example. * - value `lhs` is the left hand side which is an AST representing `abc`. * - value `declareLocalCallback` is a callback that is invoked when declaring the local. * - value `declare` is true if this value needs to be declared. * - value `localRef` is true if we are storing a local reference * - value `priority` dictates the sorting priority of this var declaration compared - * to other var declarations on the same retrieval level. For example, if there is a - * context variable and a local ref accessing the same parent view, the context var - * declaration should always come before the local ref declaration. + * to other var declarations on the same retrieval level. For example, if there is a + * context variable and a local ref accessing the same parent view, the context var + * declaration should always come before the local ref declaration. + * */ type BindingData = { retrievalLevel: number; lhs: o.Expression | LocalVarRefCallback; @@ -2686,7 +2688,8 @@ export interface ParseTemplateOptions { */ preserveWhitespaces?: boolean; /** - * Preserve original line endings instead of normalizing '\r\n' endings to '\n'. + * Preserve original line endings instead of normalizing '\\r\\n' endings to '\\n'. + * */ preserveLineEndings?: boolean; /** @@ -2753,7 +2756,6 @@ export interface ParseTemplateOptions { * Whether to always attempt to convert the parsed HTML AST to an R3 AST, despite HTML or i18n * Meta parse errors. * - * * This option is useful in the context of the language service, where we want to get as much * information as possible, despite any errors in the HTML. As an example, a user may be adding * a new tag and expecting autocomplete on that tag. In this scenario, the HTML is in an errored @@ -2762,6 +2764,7 @@ export interface ParseTemplateOptions { * * Note that even when `true` the HTML parse and i18n errors are still appended to the errors * output, but this is done after converting the HTML AST to R3 AST. + * */ alwaysAttemptHtmlToR3AstConversion?: boolean; @@ -2772,10 +2775,14 @@ export interface ParseTemplateOptions { * AST. A concrete example is @angular-eslint which requires this in order to enable * "eslint-disable" comments within HTML templates, which then allows users to turn off specific * rules on a case by case basis, instead of for their whole project within a configuration file. + * */ collectCommentNodes?: boolean; - /** Whether the @ block syntax is enabled. */ + /** + * Whether the @ block syntax is enabled. + * + */ enableBlockSyntax?: boolean; } diff --git a/packages/compiler/src/schema/dom_security_schema.ts b/packages/compiler/src/schema/dom_security_schema.ts index af24f0223b3..202e44022f6 100644 --- a/packages/compiler/src/schema/dom_security_schema.ts +++ b/packages/compiler/src/schema/dom_security_schema.ts @@ -19,7 +19,10 @@ import {SecurityContext} from '../core'; // // ================================================================================================= -/** Map from tagName|propertyName to SecurityContext. Properties applying to all tags use '*'. */ +/** + * Map from tagName|propertyName to SecurityContext. Properties applying to all tags use '\*'. + * + */ let _SECURITY_SCHEMA!: {[k: string]: SecurityContext}; export function SECURITY_SCHEMA(): {[k: string]: SecurityContext} { diff --git a/packages/compiler/src/schema/trusted_types_sinks.ts b/packages/compiler/src/schema/trusted_types_sinks.ts index 6b8e4bc3cf4..abe801d98a2 100644 --- a/packages/compiler/src/schema/trusted_types_sinks.ts +++ b/packages/compiler/src/schema/trusted_types_sinks.ts @@ -8,10 +8,11 @@ /** * Set of tagName|propertyName corresponding to Trusted Types sinks. Properties applying to all - * tags use '*'. + * tags use '\*'. * * Extracted from, and should be kept in sync with * https://w3c.github.io/webappsec-trusted-types/dist/spec/#integrations + * */ const TRUSTED_TYPES_SINKS = new Set([ // NOTE: All strings in this set *must* be lowercase! @@ -33,8 +34,10 @@ const TRUSTED_TYPES_SINKS = new Set([ * isTrustedTypesSink returns true if the given property on the given DOM tag is a Trusted Types * sink. In that case, use `ElementSchemaRegistry.securityContext` to determine which particular * Trusted Type is required for values passed to the sink: + * * - SecurityContext.HTML corresponds to TrustedHTML * - SecurityContext.RESOURCE_URL corresponds to TrustedScriptURL + * */ export function isTrustedTypesSink(tagName: string, propName: string): boolean { // Make sure comparisons are case insensitive, so that case differences between attribute and diff --git a/packages/compiler/src/selector.ts b/packages/compiler/src/selector.ts index f3c20344d0e..94147acaf55 100644 --- a/packages/compiler/src/selector.ts +++ b/packages/compiler/src/selector.ts @@ -42,14 +42,17 @@ export class CssSelector { classNames: string[] = []; /** * The selectors are encoded in pairs where: + * * - even locations are attribute names * - odd locations are attribute values. * * Example: * Selector: `[key1=value1][key2]` would parse to: + * * ``` * ['key1', 'value1', 'key2', ''] * ``` + * */ attrs: string[] = []; notSelectors: CssSelector[] = []; @@ -147,11 +150,12 @@ export class CssSelector { * Escape `$` sequences from the CSS attribute selector. * * This is needed because `$` can have a special meaning in CSS selectors, - * with this method we are escaping `$` with `\$'. + * with this method we are escaping `$` with \`\\$'. * [MDN web link for more * info](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors). + * * @param attr the attribute to escape. - * @returns the escaped string.  + * @returns the escaped string. */ escapeAttribute(attr: string): string { return attr.replace(/\\/g, '\\\\').replace(/\$/g, '\\$'); diff --git a/packages/compiler/src/template/pipeline/ir/src/expression.ts b/packages/compiler/src/template/pipeline/ir/src/expression.ts index 143a21a7bdb..14511987ed3 100644 --- a/packages/compiler/src/template/pipeline/ir/src/expression.ts +++ b/packages/compiler/src/template/pipeline/ir/src/expression.ts @@ -346,7 +346,8 @@ export class PureFunctionExpr extends ExpressionBase implements ConsumesVarsTrai * The expression which should be memoized as a pure computation. * * This expression contains internal `PureFunctionParameterExpr`s, which are placeholders for the - * positional argument expressions in `args. + * positional argument expressions in \`args. + * */ body: o.Expression|null; diff --git a/packages/compiler/src/template/pipeline/ir/src/ops/update.ts b/packages/compiler/src/template/pipeline/ir/src/ops/update.ts index f1ac1be82cc..b6e4e9ccfef 100644 --- a/packages/compiler/src/template/pipeline/ir/src/ops/update.ts +++ b/packages/compiler/src/template/pipeline/ir/src/ops/update.ts @@ -651,8 +651,10 @@ export interface I18nExpressionOp extends Op, ConsumesVarsTrait, /** * A handle for the slot that this expression modifies. + * * - In an i18n block, this is the handle of the block. * - In an i18n attribute, this is the handle of the corresponding i18nAttributes instruction. + * */ handle: SlotHandle; diff --git a/packages/compiler/src/template/pipeline/src/ingest.ts b/packages/compiler/src/template/pipeline/src/ingest.ts index 90843c73cc7..642608ecb32 100644 --- a/packages/compiler/src/template/pipeline/src/ingest.ts +++ b/packages/compiler/src/template/pipeline/src/ingest.ts @@ -730,14 +730,15 @@ function convertAst( * * Here are some of the cases we expect: * - * | Angular HTML | Template tagName | - * | ---------------------------------- | ------------------ | - * | `` | 'ng-template' | - * | `
    ` | 'div' | - * | `` | 'svg:ng-template' | - * | `@if (true) {` | 'Conditional' | - * | `` (plain) | 'ng-template' | - * | `` (structural) | null | + * | Angular HTML | Template tagName | + * | ---------------------------------- | ----------------- | + * | `` | 'ng-template' | + * | `
    ` | 'div' | + * | `` | 'svg:ng-template' | + * | `@if (true) {` | 'Conditional' | + * | `` (plain) | 'ng-template' | + * | `` (structural) | null | + * */ function isPlainTemplate(tmpl: t.Template) { return splitNsName(tmpl.tagName ?? '')[1] === 'ng-template'; @@ -987,6 +988,7 @@ function convertSourceSpan( * node has *one and only one* root element or template node. * * This approach comes with some caveats: + * * 1. As soon as any other node is added to the root, the copying behavior won't work anymore. * A diagnostic will be added to flag cases like this and to explain how to work around it. * 2. If `preserveWhitespaces` is enabled, it's very likely that indentation will break this diff --git a/packages/compiler/src/template/pipeline/src/phases/generate_variables.ts b/packages/compiler/src/template/pipeline/src/phases/generate_variables.ts index 4b18a6f3f93..1f274f77f86 100644 --- a/packages/compiler/src/template/pipeline/src/phases/generate_variables.ts +++ b/packages/compiler/src/template/pipeline/src/phases/generate_variables.ts @@ -16,14 +16,16 @@ import type {ComponentCompilationJob, ViewCompilationUnit} from '../compilation' * any variables that be referenced in other operations in the block. * * Variables generated include: - * * a saved view context to be used to restore the current view in event listeners. - * * the context of the restored view within event listener handlers. - * * context variables from the current view as well as all parent views (including the root - * context if needed). - * * local references from elements within the current view and any lexical parents. + * + * - a saved view context to be used to restore the current view in event listeners. + * - the context of the restored view within event listener handlers. + * - context variables from the current view as well as all parent views (including the root + * context if needed). + * - local references from elements within the current view and any lexical parents. * * Variables are generated here unconditionally, and may optimized away in future operations if it * turns out their values (and any side effects) are unused. + * */ export function generateVariables(job: ComponentCompilationJob): void { recursivelyProcessView(job.root, /* there is no parent scope for the root view */ null); diff --git a/packages/compiler/src/template/pipeline/src/phases/next_context_merging.ts b/packages/compiler/src/template/pipeline/src/phases/next_context_merging.ts index fc8614104fc..9adf3ea216d 100644 --- a/packages/compiler/src/template/pipeline/src/phases/next_context_merging.ts +++ b/packages/compiler/src/template/pipeline/src/phases/next_context_merging.ts @@ -19,9 +19,10 @@ import type {CompilationJob} from '../compilation'; * `NextContextExpr` that steps multiple contexts. This merging is possible if all conditions are * met: * - * * The result of the `NextContextExpr` that's folded into the subsequent one is not stored (that - * is, the call is purely side-effectful). - * * No operations in between them uses the implicit context. + * - The result of the `NextContextExpr` that's folded into the subsequent one is not stored (that + * is, the call is purely side-effectful). + * - No operations in between them uses the implicit context. + * */ export function mergeNextContextExpressions(job: CompilationJob): void { for (const unit of job.units) { diff --git a/packages/compiler/src/template/pipeline/src/phases/variable_optimization.ts b/packages/compiler/src/template/pipeline/src/phases/variable_optimization.ts index 48e9b622d32..e9094eb4e3e 100644 --- a/packages/compiler/src/template/pipeline/src/phases/variable_optimization.ts +++ b/packages/compiler/src/template/pipeline/src/phases/variable_optimization.ts @@ -17,16 +17,17 @@ import {CompilationJob} from '../compilation'; * referenced. This stage processes the list of declared variables and all variable usages, * and optimizes where possible. It performs 3 main optimizations: * - * * It transforms variable declarations to side effectful expressions when the - * variable is not used, but its initializer has global effects which other - * operations rely upon. - * * It removes variable declarations if those variables are not referenced and - * either they do not have global effects, or nothing relies on them. - * * It inlines variable declarations when those variables are only used once - * and the inlining is semantically safe. + * - It transforms variable declarations to side effectful expressions when the + * variable is not used, but its initializer has global effects which other + * operations rely upon. + * - It removes variable declarations if those variables are not referenced and + * either they do not have global effects, or nothing relies on them. + * - It inlines variable declarations when those variables are only used once + * and the inlining is semantically safe. * * To guarantee correctness, analysis of "fences" in the instruction lists is used to determine * which optimizations are safe to perform. + * */ export function optimizeVariables(job: CompilationJob): void { for (const unit of job.units) { @@ -317,8 +318,9 @@ function fencesForIrExpression(expr: ir.Expression): Fence { /** * Build the `OpInfo` structure for the given `op`. This performs two operations: * - * * It tracks which variables are used in the operation's expressions. - * * It rolls up fence flags for expressions within the operation. + * - It tracks which variables are used in the operation's expressions. + * - It rolls up fence flags for expressions within the operation. + * */ function collectOpInfo(op: ir.CreateOp|ir.UpdateOp): OpInfo { let fences = Fence.None; diff --git a/packages/core/primitives/signals/src/watch.ts b/packages/core/primitives/signals/src/watch.ts index f5dc2b66330..98668a0a604 100644 --- a/packages/core/primitives/signals/src/watch.ts +++ b/packages/core/primitives/signals/src/watch.ts @@ -34,8 +34,10 @@ export interface Watch { /** * Destroy the watcher: + * * - disconnect it from the reactive graph; * - mark it as destroyed so subsequent run and notify operations are noop. + * */ destroy(): void; diff --git a/packages/core/schematics/ng-generate/standalone-migration/prune-modules.ts b/packages/core/schematics/ng-generate/standalone-migration/prune-modules.ts index e3016c520ab..d2a935d894d 100644 --- a/packages/core/schematics/ng-generate/standalone-migration/prune-modules.ts +++ b/packages/core/schematics/ng-generate/standalone-migration/prune-modules.ts @@ -221,11 +221,13 @@ function removeExportReferences( /** * Determines whether an `@NgModule` class is safe to remove. A module is safe to remove if: + * * 1. It has no `declarations`. * 2. It has no `providers`. * 3. It has no `bootstrap` components. * 4. It has no `ModuleWithProviders` in its `imports`. * 5. It has no class members. Empty construstors are ignored. + * * @param node Class that is being checked. * @param typeChecker */ diff --git a/packages/core/schematics/utils/ng_decorators.ts b/packages/core/schematics/utils/ng_decorators.ts index 43b4fa62bde..9d4cb0892fa 100644 --- a/packages/core/schematics/utils/ng_decorators.ts +++ b/packages/core/schematics/utils/ng_decorators.ts @@ -23,6 +23,7 @@ export interface NgDecorator { /** * Gets all decorators which are imported from an Angular package (e.g. "@angular/core") * from a list of decorators. + * */ export function getAngularDecorators( typeChecker: ts.TypeChecker, decorators: ReadonlyArray): NgDecorator[] { diff --git a/packages/core/src/application_config.ts b/packages/core/src/application_config.ts index be9a7e89b95..f70b584f162 100644 --- a/packages/core/src/application_config.ts +++ b/packages/core/src/application_config.ts @@ -1,4 +1,3 @@ - /** * @license * Copyright Google LLC All Rights Reserved. diff --git a/packages/core/src/application_init.ts b/packages/core/src/application_init.ts index a55692f310a..3cb72c84988 100644 --- a/packages/core/src/application_init.ts +++ b/packages/core/src/application_init.ts @@ -26,12 +26,13 @@ import {isPromise, isSubscribable} from './util/lang'; * and the needed data is available on startup. * * @see {@link ApplicationInitStatus} - * * @usageNotes * * The following example illustrates how to configure a multi-provider using `APP_INITIALIZER` token * and a function returning a promise. + * * ### Example with NgModule-based application + * * ``` * function initializeApp(): Promise { * return new Promise((resolve, reject) => { @@ -54,6 +55,7 @@ import {isPromise, isSubscribable} from './util/lang'; * ``` * * ### Example with standalone application + * * ``` * export function initializeApp(http: HttpClient) { * return (): Promise => @@ -75,16 +77,15 @@ import {isPromise, isSubscribable} from './util/lang'; * }, * ], * }); - * ``` * - * * It's also possible to configure a multi-provider using `APP_INITIALIZER` token and a function * returning an observable, see an example below. Note: the `HttpClient` in this example is used for * demo purposes to illustrate how the factory function can work with other providers available * through DI. * * ### Example with NgModule-based application + * * ``` * function initializeAppFactory(httpClient: HttpClient): () => Observable { * return () => httpClient.get("https://someUrl.com/api/user") @@ -108,6 +109,7 @@ import {isPromise, isSubscribable} from './util/lang'; * ``` * * ### Example with standalone application + * * ``` * function initializeAppFactory(httpClient: HttpClient): () => Observable { * return () => httpClient.get("https://someUrl.com/api/user") diff --git a/packages/core/src/application_ref.ts b/packages/core/src/application_ref.ts index e393613e393..5456eec722f 100644 --- a/packages/core/src/application_ref.ts +++ b/packages/core/src/application_ref.ts @@ -427,6 +427,7 @@ export interface NgZoneOptions { * into a single change detection. * * Consider the following case. + * * ``` * for (let i = 0; i < 10; i ++) { * ngZone.run(() => { @@ -486,6 +487,7 @@ export interface BootstrapOptions { * into a single change detection. * * Consider the following case. + * * ``` * for (let i = 0; i < 10; i ++) { * ngZone.run(() => { @@ -635,6 +637,7 @@ export class PlatformRef { /** * Retrieves the platform {@link Injector}, which is the parent injector for * every Angular application on the page and provides singleton providers. + * */ get injector(): Injector { return this._injector; @@ -730,14 +733,17 @@ function optionsReducer(dst: T, objs: T|T[]): T { * A reference to an Angular application running on a page. * * @usageNotes + * * {@a is-stable-examples} + * * ### isStable examples and caveats * * Note two important points about `isStable`, demonstrated in the examples below: + * * - the application will never be stable if you start any kind - * of recurrent asynchronous task when the application starts - * (for example for a polling process, started with a `setInterval`, a `setTimeout` - * or using RxJS operators like `interval`); + * of recurrent asynchronous task when the application starts + * (for example for a polling process, started with a `setInterval`, a `setTimeout` + * or using RxJS operators like `interval`); * - the `isStable` Observable runs outside of the Angular zone. * * Let's imagine that you start a recurrent task @@ -752,6 +758,7 @@ function optionsReducer(dst: T, objs: T|T[]): T { * interval(1000).subscribe(counter => console.log(counter)); * } * ``` + * * In this example, `isStable` will never emit `true`, * and the trace "App is stable now" will never get logged. * @@ -768,6 +775,7 @@ function optionsReducer(dst: T, objs: T|T[]): T { * ).subscribe(counter => console.log(counter)); * } * ``` + * * In this example, the trace "App is stable now" will be logged * and then the counter starts incrementing every second. * @@ -787,6 +795,7 @@ function optionsReducer(dst: T, objs: T|T[]): T { * ).subscribe(counter => this.value = counter); * } * ``` + * * As the `isStable` Observable runs outside the zone, * the `value` field will be updated properly, * but the template will not be refreshed! @@ -872,6 +881,7 @@ export class ApplicationRef { * specified element. * * @usageNotes + * * ### Bootstrap process * * When bootstrapping a component, Angular mounts it onto a target DOM element @@ -903,6 +913,7 @@ export class ApplicationRef { * While in this example, we are providing reference to a DOM node. * * {@example core/ts/platform/platform.ts region='domNode'} + * */ bootstrap(component: Type, rootSelectorOrNode?: string|any): ComponentRef; @@ -911,6 +922,7 @@ export class ApplicationRef { * specified element. * * @usageNotes + * * ### Bootstrap process * * When bootstrapping a component, Angular mounts it onto a target DOM element @@ -954,6 +966,7 @@ export class ApplicationRef { * specified element. * * @usageNotes + * * ### Bootstrap process * * When bootstrapping a component, Angular mounts it onto a target DOM element @@ -985,6 +998,7 @@ export class ApplicationRef { * While in this example, we are providing reference to a DOM node. * * {@example core/ts/platform/platform.ts region='domNode'} + * */ bootstrap(componentOrFactory: ComponentFactory|Type, rootSelectorOrNode?: string|any): ComponentRef { diff --git a/packages/core/src/application_tokens.ts b/packages/core/src/application_tokens.ts index 9b1acc63dc0..75fb018fe0c 100644 --- a/packages/core/src/application_tokens.ts +++ b/packages/core/src/application_tokens.ts @@ -117,15 +117,17 @@ export const CSP_NONCE = new InjectionToken('CSP nonce', { /** * A configuration object for the image-related options. Contains: + * * - breakpoints: An array of integer breakpoints used to generate * srcsets for responsive images. * - disableImageSizeWarning: A boolean value. Setting this to true will * disable console warnings about oversized images. * - disableImageLazyLoadWarning: A boolean value. Setting this to true will - * disable console warnings about LCP images configured with `loading="lazy"`. - * Learn more about the responsive image configuration in [the NgOptimizedImage - * guide](guide/image-directive). - * Learn more about image warning options in [the related error page](errors/NG0913). + * disable console warnings about LCP images configured with `loading="lazy"`. + * Learn more about the responsive image configuration in [the NgOptimizedImage + * guide](guide/image-directive). + * Learn more about image warning options in [the related error page](errors/NG0913). + * * @publicApi */ export type ImageConfig = { diff --git a/packages/core/src/change_detection/change_detector_ref.ts b/packages/core/src/change_detection/change_detector_ref.ts index 0f0fac68eae..682e3f91acd 100644 --- a/packages/core/src/change_detection/change_detector_ref.ts +++ b/packages/core/src/change_detection/change_detector_ref.ts @@ -23,7 +23,6 @@ import {ViewRef} from '../render3/view_ref'; * * @see [Using change detection hooks](guide/lifecycle-hooks#using-change-detection-hooks) * @see [Defining custom change detection](guide/lifecycle-hooks#defining-custom-change-detection) - * * @usageNotes * * The following examples demonstrate how to modify default change-detection behavior @@ -48,7 +47,6 @@ import {ViewRef} from '../render3/view_ref'; * * * - * * ### Reattaching a detached component * * The following example creates a component displaying live data. @@ -84,6 +82,7 @@ export abstract class ChangeDetectorRef { * re-attached, even if they are marked as dirty. * * + * * * */ @@ -94,6 +93,7 @@ export abstract class ChangeDetectorRef { * to implement local change detection checks. * * + * * * */ diff --git a/packages/core/src/change_detection/differs/default_iterable_differ.ts b/packages/core/src/change_detection/differs/default_iterable_differ.ts index 54405452cd5..399d3985ad6 100644 --- a/packages/core/src/change_detection/differs/default_iterable_differ.ts +++ b/packages/core/src/change_detection/differs/default_iterable_differ.ts @@ -321,8 +321,8 @@ export class DefaultIterableDiffer implements IterableDiffer, IterableChan * If we did not have this check then the insertion of `b` would: * 1) evict first `a` * 2) insert `b` at `0` index. - * 3) leave `a` at index `1` as is. <-- this is wrong! - * 3) reinsert `a` at index 2. <-- this is wrong! + * 3) leave `a` at index `1` as is. <-- this is wrong! + * 3) reinsert `a` at index 2. <-- this is wrong! * * The correct behavior is: * 1) evict first `a` @@ -330,7 +330,6 @@ export class DefaultIterableDiffer implements IterableDiffer, IterableChan * 3) reinsert `a` at index 1. * 3) move `a` at from `1` to `2`. * - * * Double check that we have not evicted a duplicate item. We need to check if the item type may * have already been removed: * The insertion of b will evict the first 'a'. If we don't reinsert it now it will be reinserted @@ -354,9 +353,9 @@ export class DefaultIterableDiffer implements IterableDiffer, IterableChan } /** - * Get rid of any excess {@link IterableChangeRecord_}s from the previous collection + * Get rid of any excess {@link IterableChangeRecord\_}s from the previous collection * - * - `record` The first excess {@link IterableChangeRecord_}. + * - `record` The first excess {@link IterableChangeRecord\_}. * * @internal */ @@ -639,9 +638,10 @@ class _DuplicateItemRecordList { } /** - * Remove one {@link IterableChangeRecord_} from the list of duplicates. + * Remove one {@link IterableChangeRecord\_} from the list of duplicates. * * Returns whether the list of duplicates is empty. + * */ remove(record: IterableChangeRecord_): boolean { // TODO(vicb): @@ -684,11 +684,12 @@ class _DuplicateMap { } /** - * Retrieve the `value` using key. Because the IterableChangeRecord_ value may be one which we + * Retrieve the `value` using key. Because the IterableChangeRecord\_ value may be one which we * have already iterated over, we use the `atOrAfterIndex` to pretend it is not there. * * Use case: `[a, b, c, a, a]` if we are at index `3` which is the second `a` then asking if we * have any more `a`s needs to return the second `a`. + * */ get(trackById: any, atOrAfterIndex: number|null): IterableChangeRecord_|null { const key = trackById; @@ -697,9 +698,10 @@ class _DuplicateMap { } /** - * Removes a {@link IterableChangeRecord_} from the list of duplicates. + * Removes a {@link IterableChangeRecord\_} from the list of duplicates. * * The list of duplicates also is removed from the map if it gets empty. + * */ remove(record: IterableChangeRecord_): IterableChangeRecord_ { const key = record.trackById; diff --git a/packages/core/src/change_detection/differs/iterable_differs.ts b/packages/core/src/change_detection/differs/iterable_differs.ts index 83e385d3874..43aba1fd0df 100644 --- a/packages/core/src/change_detection/differs/iterable_differs.ts +++ b/packages/core/src/change_detection/differs/iterable_differs.ts @@ -120,7 +120,6 @@ export interface IterableChangeRecord { * `NgForOf` needs to uniquely identify items in the iterable to correctly perform DOM updates * when items in the iterable are reordered, new items are added, or existing items are removed. * - * * In all of these scenarios it is usually desirable to only update the DOM elements associated * with the items affected by the change. This behavior is important to: * @@ -140,7 +139,9 @@ export interface IterableChangeRecord { * ... * } * ``` + * * a custom `trackBy` function could look like the following: + * * ```ts * function userTrackBy(index, user) { * return user.id; @@ -150,7 +151,7 @@ export interface IterableChangeRecord { * A custom `trackBy` function must have several properties: * * - be [idempotent](https://en.wikipedia.org/wiki/Idempotence) (be without side effects, and always - * return the same value for a given input) + * return the same value for a given input) * - return unique value for all unique inputs * - be fast * @@ -212,6 +213,7 @@ export class IterableDiffers { * {@link IterableDiffers} instance. * * @usageNotes + * * ### Example * * The following example shows how to extend an existing list of factories, @@ -225,6 +227,7 @@ export class IterableDiffers { * ] * }) * ``` + * */ static extend(factories: IterableDifferFactory[]): StaticProvider { return { diff --git a/packages/core/src/change_detection/differs/keyvalue_differs.ts b/packages/core/src/change_detection/differs/keyvalue_differs.ts index ae3a0e005ca..1ad6536b0bd 100644 --- a/packages/core/src/change_detection/differs/keyvalue_differs.ts +++ b/packages/core/src/change_detection/differs/keyvalue_differs.ts @@ -150,6 +150,7 @@ export class KeyValueDiffers { * {@link KeyValueDiffers} instance. * * @usageNotes + * * ### Example * * The following example shows how to extend an existing list of factories, @@ -163,6 +164,7 @@ export class KeyValueDiffers { * ] * }) * ``` + * */ static extend(factories: KeyValueDifferFactory[]): StaticProvider { return { diff --git a/packages/core/src/compiler/compiler_facade_interface.ts b/packages/core/src/compiler/compiler_facade_interface.ts index 09fd34f5676..3514f9a1fee 100644 --- a/packages/core/src/compiler/compiler_facade_interface.ts +++ b/packages/core/src/compiler/compiler_facade_interface.ts @@ -11,14 +11,17 @@ * for late binding of `@angular/compiler` for JIT purposes. * * This file has two copies. Please ensure that they are in sync: - * - packages/compiler/src/compiler_facade_interface.ts (main) - * - packages/core/src/compiler/compiler_facade_interface.ts (replica) + * + * - packages/compiler/src/compiler_facade_interface.ts (main) + * - packages/core/src/compiler/compiler_facade_interface.ts (replica) * * Please ensure that the two files are in sync using this command: + * * ``` * cp packages/compiler/src/compiler_facade_interface.ts \ * packages/core/src/compiler/compiler_facade_interface.ts * ``` + * */ export interface ExportedCompilerFacade { diff --git a/packages/core/src/debug/debug_node.ts b/packages/core/src/debug/debug_node.ts index 2b2cd11fcf2..f215109e574 100644 --- a/packages/core/src/debug/debug_node.ts +++ b/packages/core/src/debug/debug_node.ts @@ -75,8 +75,9 @@ export class DebugNode { * that governs this element. * * When an element is repeated within *ngFor, the context is an `NgForOf` whose `$implicit` - * property is the value of the row instance value. For example, the `hero` in `*ngFor="let hero - * of heroes"`. + * property is the value of the row instance value. For example, the `hero` in \`*ngFor="let hero + * of heroes"\`. + * */ get context(): any { return getComponent(this.nativeNode as Element) || getContext(this.nativeNode as Element); @@ -85,6 +86,7 @@ export class DebugNode { /** * The callbacks attached to the component's @Output properties and/or the element's event * properties. + * */ get listeners(): DebugEventListener[] { return getListeners(this.nativeNode as Element).filter(listener => listener.type === 'dom'); @@ -144,16 +146,22 @@ export class DebugElement extends DebugNode { } /** - * Gets a map of property names to property values for an element. + * Gets a map of property names to property values for an element. * * This map includes: - * - Regular property bindings (e.g. `[id]="id"`) - * - Host property bindings (e.g. `host: { '[id]': "id" }`) - * - Interpolated property bindings (e.g. `id="{{ value }}") * - * It does not include: - * - input property bindings (e.g. `[myCustomInput]="value"`) - * - attribute bindings (e.g. `[attr.role]="menu"`) + * - Regular property bindings (e.g. `[id]="id"`) + * + * - Host property bindings (e.g. `host: { '[id]': "id" }`) + * + * - Interpolated property bindings (e.g. \`id="{{ value }}") + * + * It does not include: + * + * - input property bindings (e.g. `[myCustomInput]="value"`) + * + * - attribute bindings (e.g. `[attr.role]="menu"`) + * */ get properties(): {[key: string]: any;} { const context = getLContext(this.nativeNode)!; diff --git a/packages/core/src/defer/instructions.ts b/packages/core/src/defer/instructions.ts index c6759f3cfe8..51e3f05f1c6 100644 --- a/packages/core/src/defer/instructions.ts +++ b/packages/core/src/defer/instructions.ts @@ -405,7 +405,10 @@ export function ɵɵdeferPrefetchOnViewport(triggerIndex: number, walkUpTimes?: } } -/********** Helper functions **********/ +/** + * **\*\*\*** Helper functions + * + */ /** * Schedules triggering of a defer block for `on idle` and `on timer` conditions. diff --git a/packages/core/src/defer/interfaces.ts b/packages/core/src/defer/interfaces.ts index ed2285e27ad..a93122747ef 100644 --- a/packages/core/src/defer/interfaces.ts +++ b/packages/core/src/defer/interfaces.ts @@ -105,8 +105,9 @@ export interface TDeferBlockDetails { /** * Dependency loading Promise. This Promise is helpful for cases when there - * are multiple instances of a defer block (e.g. if it was used inside of an *ngFor), + * are multiple instances of a defer block (e.g. if it was used inside of an \*ngFor), * which all await the same set of dependencies. + * */ loadingPromise: Promise|null; } diff --git a/packages/core/src/defer/utils.ts b/packages/core/src/defer/utils.ts index 8ec90c120b2..06d37cf41bb 100644 --- a/packages/core/src/defer/utils.ts +++ b/packages/core/src/defer/utils.ts @@ -93,7 +93,10 @@ export function getMinimumDurationForState( return null; } -/** Retrieves the value of the `after` parameter on the @loading block. */ +/** + * Retrieves the value of the `after` parameter on the @loading block. + * + */ export function getLoadingBlockAfter(tDetails: TDeferBlockDetails): number|null { return tDetails.loadingBlockConfig?.[LOADING_AFTER_SLOT] ?? null; } diff --git a/packages/core/src/di/forward_ref.ts b/packages/core/src/di/forward_ref.ts index ff197f1a133..02090aa021e 100644 --- a/packages/core/src/di/forward_ref.ts +++ b/packages/core/src/di/forward_ref.ts @@ -16,9 +16,11 @@ import {stringify} from '../util/stringify'; * An interface that a function passed into {@link forwardRef} has to implement. * * @usageNotes + * * ### Example * * {@example core/di/ts/forward_ref/forward_ref_spec.ts region='forward_ref_fn'} + * * @publicApi */ export interface ForwardRefFn { @@ -37,10 +39,13 @@ const __forward_ref__ = getClosureSafeProperty({__forward_ref__: getClosureSafeP * `forwardRef` is also used to break circularities in standalone components imports. * * @usageNotes + * * ### Circular dependency example + * * {@example core/di/ts/forward_ref/forward_ref_spec.ts region='forward_ref'} * * ### Circular standalone reference import example + * * ```ts * @Component({ * standalone: true, @@ -52,7 +57,6 @@ const __forward_ref__ = getClosureSafeProperty({__forward_ref__: getClosureSafeP * @Input() hideParent: boolean; * } * - * * @Component({ * standalone: true, * imports: [CommonModule, forwardRef(() => ParentComponent)], @@ -80,6 +84,7 @@ export function forwardRef(forwardRefFn: ForwardRefFn): Type { * Acts as the identity function when given a non-forward-ref value. * * @usageNotes + * * ### Example * * {@example core/di/ts/forward_ref/forward_ref_spec.ts region='resolve_forward_ref'} diff --git a/packages/core/src/di/inject_switch.ts b/packages/core/src/di/inject_switch.ts index a780c13a75d..97987fcbcf6 100644 --- a/packages/core/src/di/inject_switch.ts +++ b/packages/core/src/di/inject_switch.ts @@ -21,8 +21,10 @@ import {ProviderToken} from './provider_token'; * By default, it is `injectInjectorOnly`, which makes it `Injector`-only aware. It can be changed * to `directiveInject`, which brings in the `NodeInjector` system of ivy. It is designed this * way for two reasons: - * 1. `Injector` should not depend on ivy logic. - * 2. To maintain tree shake-ability we don't want to bring in unnecessary code. + * + * 1. `Injector` should not depend on ivy logic. + * 1. To maintain tree shake-ability we don't want to bring in unnecessary code. + * */ let _injectImplementation: ((token: ProviderToken, flags?: InjectFlags) => T | null)| undefined; diff --git a/packages/core/src/di/injectable.ts b/packages/core/src/di/injectable.ts index d92500e9459..32d122b987c 100644 --- a/packages/core/src/di/injectable.ts +++ b/packages/core/src/di/injectable.ts @@ -65,18 +65,19 @@ export interface Injectable { * Determines which injectors will provide the injectable. * * - `Type` - associates the injectable with an `@NgModule` or other `InjectorType`. This - * option is DEPRECATED. + * option is DEPRECATED. * - 'null' : Equivalent to `undefined`. The injectable is not provided in any scope automatically - * and must be added to a `providers` array of an [@NgModule](api/core/NgModule#providers), - * [@Component](api/core/Directive#providers) or [@Directive](api/core/Directive#providers). + * and must be added to a `providers` array of an [@NgModule](api/core/NgModule#providers), + * [@Component](api/core/Directive#providers) or [@Directive](api/core/Directive#providers). * * The following options specify that this injectable should be provided in one of the following * injectors: + * * - 'root' : The application-level injector in most apps. * - 'platform' : A special singleton platform injector shared by all - * applications on the page. + * applications on the page. * - 'any' : Provides a unique instance in each lazy loaded module while all eagerly loaded - * modules share one instance. This option is DEPRECATED. + * modules share one instance. This option is DEPRECATED. * */ providedIn?: Type|'root'|'platform'|'any'|null; diff --git a/packages/core/src/di/injection_token.ts b/packages/core/src/di/injection_token.ts index 822bb92c0cb..7f63e2f8512 100644 --- a/packages/core/src/di/injection_token.ts +++ b/packages/core/src/di/injection_token.ts @@ -48,6 +48,7 @@ import {ɵɵdefineInjectable} from './interface/defs'; * The `providedIn: NgModule` and `providedIn: 'any'` options are deprecated. * * @usageNotes + * * ### Basic Examples * * ### Plain InjectionToken diff --git a/packages/core/src/di/injector.ts b/packages/core/src/di/injector.ts index a7b6394330d..c8e1ef88c66 100644 --- a/packages/core/src/di/injector.ts +++ b/packages/core/src/di/injector.ts @@ -24,10 +24,9 @@ import {ProviderToken} from './provider_token'; * * @see ["DI Providers"](guide/dependency-injection-providers). * @see {@link StaticProvider} - * * @usageNotes * - * The following example creates a service injector instance. + * The following example creates a service injector instance. * * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'} * @@ -97,12 +96,12 @@ export abstract class Injector { * according to a given type or types of `StaticProvider`. * * @param options An object with the following properties: + * * * `providers`: An array of providers of the [StaticProvider type](api/core/StaticProvider). * * `parent`: (optional) A parent injector. * * `name`: (optional) A developer-defined identifying name for the new injector. * * @returns The new injector instance. - * */ static create(options: {providers: Array, parent?: Injector, name?: string}): diff --git a/packages/core/src/di/injector_compatibility.ts b/packages/core/src/di/injector_compatibility.ts index e23bbcce9eb..4a038b3ca38 100644 --- a/packages/core/src/di/injector_compatibility.ts +++ b/packages/core/src/di/injector_compatibility.ts @@ -38,9 +38,11 @@ export const SOURCE = '__source'; /** * Current injector value used by `inject`. + * * - `undefined`: it is an error to call `inject` * - `null`: `inject` can be called but there is no injector (limp-mode). * - Injector instance: Use the injector for resolution. + * */ let _currentInjector: Injector|undefined|null = undefined; @@ -157,8 +159,9 @@ export function inject(token: ProviderToken, options: InjectOptions): T|nu * Injects a token from the currently active injector. * `inject` is only supported in an [injection context](/guide/dependency-injection-context). It can * be used during: + * * - Construction (via the `constructor`) of a class being instantiated by the DI system, such - * as an `@Injectable` or `@Component`. + * as an `@Injectable` or `@Component`. * - In the initializer for fields of such classes. * - In the factory function specified for `useFactory` of a `Provider` or an `@Injectable`. * - In the `factory` function specified for an `InjectionToken`. @@ -170,7 +173,6 @@ export function inject(token: ProviderToken, options: InjectOptions): T|nu * parameter decorators `@Host`, `@Self`, `@SkipSelf`, and `@Optional`. * @returns the injected value if operation is successful, `null` otherwise. * @throws if called outside of a supported context. - * * @usageNotes * In practice the `inject()` calls are allowed in a constructor, a constructor parameter and a * field initializer: @@ -215,7 +217,6 @@ export function inject(token: ProviderToken, options: InjectOptions): T|nu * } * } * ``` - * * @publicApi */ export function inject( diff --git a/packages/core/src/di/interface/defs.ts b/packages/core/src/di/interface/defs.ts index 37224294a8a..4be4bce0ec9 100644 --- a/packages/core/src/di/interface/defs.ts +++ b/packages/core/src/di/interface/defs.ts @@ -31,11 +31,13 @@ import {ClassProvider, ConstructorProvider, EnvironmentProviders, ExistingProvid export interface ɵɵInjectableDeclaration { /** * Specifies that the given type belongs to a particular injector: + * * - `InjectorType` such as `NgModule`, * - `'root'` the root injector * - `'any'` all injectors. * - `null`, does not belong to any injector. Must be explicitly listed in the injector * `providers`. + * */ providedIn: InjectorType|'root'|'platform'|'any'|'environment'|null; @@ -131,12 +133,13 @@ export interface InjectorTypeWithProviders { * `InjectableType`. * * Options: + * * * `providedIn` determines which injectors will include the injectable, by either associating it * with an `@NgModule` or other `InjectorType`, or by specifying that this injectable should be * provided in the `'root'` injector, which will be the application-level injector in most apps. * * `factory` gives the zero argument function which will create an instance of the injectable. - * The factory can call [`inject`](api/core/inject) to access the `Injector` and request injection - * of dependencies. + * The factory can call [`inject`](api/core/inject) to access the `Injector` and request injection + * of dependencies. * * @codeGenApi * @publicApi This instruction has been emitted by ViewEngine for some time and is deployed to npm. diff --git a/packages/core/src/di/interface/provider.ts b/packages/core/src/di/interface/provider.ts index e3dd959df11..5bda4d02806 100644 --- a/packages/core/src/di/interface/provider.ts +++ b/packages/core/src/di/interface/provider.ts @@ -24,7 +24,6 @@ export interface ValueSansProvider { /** * Configures the `Injector` to return a value for a token. * @see ["Dependency Injection Guide"](guide/dependency-injection). - * * @usageNotes * * ### Example @@ -73,7 +72,6 @@ export interface StaticClassSansProvider { /** * Configures the `Injector` to return an instance of `useClass` for a token. * @see ["Dependency Injection Guide"](guide/dependency-injection). - * * @usageNotes * * {@example core/di/ts/provider_spec.ts region='StaticClassProvider'} @@ -126,7 +124,6 @@ export interface ConstructorSansProvider { * Configures the `Injector` to return an instance of a token. * * @see ["Dependency Injection Guide"](guide/dependency-injection). - * * @usageNotes * * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'} @@ -169,7 +166,6 @@ export interface ExistingSansProvider { * Configures the `Injector` to return a value of another `useExisting` token. * * @see ["Dependency Injection Guide"](guide/dependency-injection). - * * @usageNotes * * {@example core/di/ts/provider_spec.ts region='ExistingProvider'} @@ -218,7 +214,6 @@ export interface FactorySansProvider { /** * Configures the `Injector` to return a value by invoking a `useFactory` function. * @see ["Dependency Injection Guide"](guide/dependency-injection). - * * @usageNotes * * {@example core/di/ts/provider_spec.ts region='FactoryProvider'} @@ -260,7 +255,7 @@ export type StaticProvider = /** - * Configures the `Injector` to return an instance of `Type` when `Type' is used as the token. + * Configures the `Injector` to return an instance of `Type` when \`Type' is used as the token. * * Create an instance by invoking the `new` operator and supplying additional arguments. * This form is a short form of `TypeProvider`; @@ -293,7 +288,6 @@ export interface ClassSansProvider { /** * Configures the `Injector` to return an instance of `useClass` for a token. * @see ["Dependency Injection Guide"](guide/dependency-injection). - * * @usageNotes * * {@example core/di/ts/provider_spec.ts region='ClassProvider'} @@ -376,11 +370,9 @@ export type ProcessProvidersFunction = (providers: Provider[]) => Provider[]; /** - * A wrapper around an NgModule that associates it with [providers](guide/glossary#provider - * "Definition"). Usage without a generic type is deprecated. + * A wrapper around an NgModule that associates it with [providers](guide/glossary#provider "Definition"). Usage without a generic type is deprecated. * * @see [Deprecations](guide/deprecations#modulewithproviders-type-without-a-generic) - * * @publicApi */ export interface ModuleWithProviders { diff --git a/packages/core/src/di/jit/environment.ts b/packages/core/src/di/jit/environment.ts index d1402174ebb..299ea54ca0e 100644 --- a/packages/core/src/di/jit/environment.ts +++ b/packages/core/src/di/jit/environment.ts @@ -13,6 +13,7 @@ import {ɵɵdefineInjectable, ɵɵdefineInjector} from '../interface/defs'; * A mapping of the @angular/core API surface used in generated expressions to the actual symbols. * * This should be kept up to date with the public exports of @angular/core. + * */ export const angularCoreDiEnv: {[name: string]: Function} = { 'ɵɵdefineInjectable': ɵɵdefineInjectable, diff --git a/packages/core/src/error_details_base_url.ts b/packages/core/src/error_details_base_url.ts index 417f681e355..860c2ba2f19 100644 --- a/packages/core/src/error_details_base_url.ts +++ b/packages/core/src/error_details_base_url.ts @@ -10,8 +10,10 @@ * Base URL for the error details page. * * Keep this constant in sync across: - * - packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts - * - packages/core/src/error_details_base_url.ts + * + * - packages/compiler-cli/src/ngtsc/diagnostics/src/error_details_base_url.ts + * - packages/core/src/error_details_base_url.ts + * */ export const ERROR_DETAILS_PAGE_BASE_URL = 'https://angular.io/errors'; diff --git a/packages/core/src/errors.ts b/packages/core/src/errors.ts index 2ccbd00a93a..35c898335fc 100644 --- a/packages/core/src/errors.ts +++ b/packages/core/src/errors.ts @@ -19,12 +19,14 @@ import {ERROR_DETAILS_PAGE_BASE_URL} from './error_details_base_url'; * Full list of available error guides can be found at https://angular.io/errors. * * Error code ranges per package: - * - core (this package): 100-999 - * - forms: 1000-1999 - * - common: 2000-2999 - * - animations: 3000-3999 - * - router: 4000-4999 - * - platform-browser: 5000-5500 + * + * - core (this package): 100-999 + * - forms: 1000-1999 + * - common: 2000-2999 + * - animations: 3000-3999 + * - router: 4000-4999 + * - platform-browser: 5000-5500 + * */ export const enum RuntimeErrorCode { // Change Detection Errors @@ -128,6 +130,7 @@ export const enum RuntimeErrorCode { * Formats and outputs the error message in a consistent way. * * Example: + * * ``` * throw new RuntimeError( * RuntimeErrorCode.INJECTOR_ALREADY_DESTROYED, @@ -138,6 +141,7 @@ export const enum RuntimeErrorCode { * mode (when the `ngDevMode` is defined). In production mode (after tree-shaking pass), the * `message` argument becomes `false`, thus we account for it in the typings and the runtime * logic. + * */ export class RuntimeError extends Error { constructor(public code: T, message: null|false|string) { diff --git a/packages/core/src/hydration/annotate.ts b/packages/core/src/hydration/annotate.ts index 5e02676dbe1..b7ee5dc7093 100644 --- a/packages/core/src/hydration/annotate.ts +++ b/packages/core/src/hydration/annotate.ts @@ -473,14 +473,15 @@ function serializeLView(lView: LView, context: HydrationContext): SerializedView /** * Serializes node location in cases when it's needed, specifically: * - * 1. If `tNode.projectionNext` is different from `tNode.next` - it means that - * the next `tNode` after projection is different from the one in the original - * template. Since hydration relies on `tNode.next`, this serialized info - * if required to help runtime code find the node at the correct location. - * 2. In certain content projection-based use-cases, it's possible that only - * a content of a projected element is rendered. In this case, content nodes - * require an extra annotation, since runtime logic can't rely on parent-child - * connection to identify the location of a node. + * 1. If `tNode.projectionNext` is different from `tNode.next` - it means that + * the next `tNode` after projection is different from the one in the original + * template. Since hydration relies on `tNode.next`, this serialized info + * if required to help runtime code find the node at the correct location. + * 1. In certain content projection-based use-cases, it's possible that only + * a content of a projected element is rendered. In this case, content nodes + * require an extra annotation, since runtime logic can't rely on parent-child + * connection to identify the location of a node. + * */ function conditionallyAnnotateNodePath(ngh: SerializedView, tNode: TNode, lView: LView) { // Handle case #1 described above. @@ -512,6 +513,7 @@ function componentUsesShadowDomEncapsulation(lView: LView): boolean { /** * Annotates component host element for hydration: + * * - by either adding the `ngh` attribute and collecting hydration-related info * for the serialization and transferring to the client * - or by adding the `ngSkipHydration` attribute in case Angular detects that diff --git a/packages/core/src/hydration/compression.ts b/packages/core/src/hydration/compression.ts index b61d146cf55..03b76e0f3e8 100644 --- a/packages/core/src/hydration/compression.ts +++ b/packages/core/src/hydration/compression.ts @@ -11,9 +11,11 @@ import {NodeNavigationStep, REFERENCE_NODE_BODY, REFERENCE_NODE_HOST} from './in /** * Regexp that extracts a reference node information from the compressed node location. * The reference node is represented as either: - * - a number which points to an LView slot - * - the `b` char which indicates that the lookup should start from the `document.body` - * - the `h` char to start lookup from the component host node (`lView[HOST]`) + * + * - a number which points to an LView slot + * - the `b` char which indicates that the lookup should start from the `document.body` + * - the `h` char to start lookup from the component host node (`lView[HOST]`) + * */ const REF_EXTRACTOR_REGEXP = new RegExp(`^(\\d+)*(${REFERENCE_NODE_BODY}|${REFERENCE_NODE_HOST})*(.*)`); diff --git a/packages/core/src/hydration/interfaces.ts b/packages/core/src/hydration/interfaces.ts index 5b1a25c8a7d..34497526e40 100644 --- a/packages/core/src/hydration/interfaces.ts +++ b/packages/core/src/hydration/interfaces.ts @@ -103,9 +103,11 @@ export interface SerializedContainerView extends SerializedView { /** * Unique id that represents a TView that was used to create * a given instance of a view: - * - TViewType.Embedded: a unique id generated during serialization on the server - * - TViewType.Component: an id generated based on component properties - * (see `getComponentId` function for details) + * + * - TViewType.Embedded: a unique id generated during serialization on the server + * - TViewType.Component: an id generated based on component properties + * (see `getComponentId` function for details) + * */ [TEMPLATE_ID]: string; @@ -119,7 +121,8 @@ export interface SerializedContainerView extends SerializedView { /** * Number of times this view is repeated. * This is used to avoid serializing and sending the same hydration - * information about similar views (for example, produced by *ngFor). + * information about similar views (for example, produced by \*ngFor). + * */ [MULTIPLIER]?: number; } diff --git a/packages/core/src/hydration/node_lookup_utils.ts b/packages/core/src/hydration/node_lookup_utils.ts index 0001c257cd8..4c02f7a4530 100644 --- a/packages/core/src/hydration/node_lookup_utils.ts +++ b/packages/core/src/hydration/node_lookup_utils.ts @@ -233,10 +233,12 @@ function navigateBetweenSiblings(start: Node, finish: Node): NodeNavigationStep[ /** * Calculates a path between 2 nodes in terms of `nextSibling` and `firstChild` * navigations: + * * - the `from` node is a known node, used as an starting point for the lookup * (the `fromNodeName` argument is a string representation of the node). * - the `to` node is a node that the runtime logic would be looking up, * using the path generated by this function. + * */ export function calcPathBetween(from: Node, to: Node, fromNodeName: string): string|null { const path = navigateBetween(from, to); diff --git a/packages/core/src/hydration/utils.ts b/packages/core/src/hydration/utils.ts index 9d288ca2cce..e3c5ccd385c 100644 --- a/packages/core/src/hydration/utils.ts +++ b/packages/core/src/hydration/utils.ts @@ -1,4 +1,3 @@ - /** * @license * Copyright Google LLC All Rights Reserved. @@ -174,9 +173,11 @@ export function retrieveHydrationInfo( /** * Retrieves the necessary object from a given ViewRef to serialize: - * - an LView for component views - * - an LContainer for cases when component acts as a ViewContainerRef anchor - * - `null` in case of an embedded view + * + * - an LView for component views + * - an LContainer for cases when component acts as a ViewContainerRef anchor + * - `null` in case of an embedded view + * */ export function getLNodeForHydration(viewRef: ViewRef): LView|LContainer|null { // Reading an internal field from `ViewRef` instance. @@ -283,7 +284,8 @@ export function getSegmentHead(hydrationInfo: DehydratedView, index: number): RN * serialized in `ELEMENT_CONTAINERS` (element container size) or by * computing the sum of root nodes in all dehydrated views in a given * container (in case this `` was also used as a view - * container host node, e.g. ). + * container host node, e.g. <ng-container \*ngIf>). + * */ export function getNgContainerSize(hydrationInfo: DehydratedView, index: number): number|null { const data = hydrationInfo.data; diff --git a/packages/core/src/i18n/tokens.ts b/packages/core/src/i18n/tokens.ts index 175eb3bc201..2c883379189 100644 --- a/packages/core/src/i18n/tokens.ts +++ b/packages/core/src/i18n/tokens.ts @@ -156,7 +156,6 @@ export const TRANSLATIONS = new InjectionToken('Translations'); * providers: [{provide: TRANSLATIONS_FORMAT, useValue: 'xlf' }] * }); * ``` - * * @publicApi */ export const TRANSLATIONS_FORMAT = new InjectionToken('TranslationsFormat'); @@ -164,6 +163,7 @@ export const TRANSLATIONS_FORMAT = new InjectionToken('TranslationsForma /** * Use this enum at bootstrap as an option of `bootstrapModule` to define the strategy * that the compiler should use in case of missing translations: + * * - Error: throw if you have missing translations. * - Warning (default): show a warning in the console and/or shell. * - Ignore: do nothing. @@ -171,7 +171,9 @@ export const TRANSLATIONS_FORMAT = new InjectionToken('TranslationsForma * See the [i18n guide](guide/i18n-common-merge#report-missing-translations) for more information. * * @usageNotes + * * ### Example + * * ```typescript * import { MissingTranslationStrategy } from '@angular/core'; * import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; diff --git a/packages/core/src/interface/lifecycle_hooks.ts b/packages/core/src/interface/lifecycle_hooks.ts index 334fbbc21c1..c312aa52896 100644 --- a/packages/core/src/interface/lifecycle_hooks.ts +++ b/packages/core/src/interface/lifecycle_hooks.ts @@ -12,12 +12,11 @@ import {SimpleChanges} from './simple_change'; * @description * A lifecycle hook that is called when any data-bound property of a directive changes. * Define an `ngOnChanges()` method to handle the changes. - * * @see {@link DoCheck} * @see {@link OnInit} * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface to * define an on-changes handler for an input property. * @@ -41,11 +40,10 @@ export interface OnChanges { * A lifecycle hook that is called after Angular has initialized * all data-bound properties of a directive. * Define an `ngOnInit()` method to handle any additional initialization tasks. - * * @see {@link AfterContentInit} * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface to * define its own initialization method. * @@ -79,8 +77,8 @@ export interface OnInit { * * @see {@link OnChanges} * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface * to invoke it own change-detection cycle. * @@ -107,8 +105,8 @@ export interface DoCheck { * Use for any custom cleanup that needs to occur when the * instance is destroyed. * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface * to define its own custom clean-up method. * @@ -129,12 +127,11 @@ export interface OnDestroy { * A lifecycle hook that is called after Angular has fully initialized * all content of a directive. It will run only once when the projected content is initialized. * Define an `ngAfterContentInit()` method to handle any additional initialization tasks. - * * @see {@link OnInit} * @see {@link AfterViewInit} * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface to * define its own content initialization method. * @@ -157,11 +154,10 @@ export interface AfterContentInit { * A lifecycle hook that is called after the default change detector has * completed checking all content of a directive. It will run after the content * has been checked and most of the time it's during a change detection cycle. - * * @see {@link AfterViewChecked} * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface to * define its own after-check functionality. * @@ -183,12 +179,11 @@ export interface AfterContentChecked { * A lifecycle hook that is called after Angular has fully initialized * a component's view. * Define an `ngAfterViewInit()` method to handle any additional initialization tasks. - * * @see {@link OnInit} * @see {@link AfterContentInit} * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface to * define its own view initialization method. * @@ -210,11 +205,10 @@ export interface AfterViewInit { * @description * A lifecycle hook that is called after the default change detector has * completed checking a component's view for changes. - * * @see {@link AfterContentChecked} * @see [Lifecycle hooks guide](guide/lifecycle-hooks) - * * @usageNotes + * * The following snippet shows how a component can implement this interface to * define its own after-check functionality. * diff --git a/packages/core/src/interface/simple_change.ts b/packages/core/src/interface/simple_change.ts index 76c608dc558..8d5dae32364 100644 --- a/packages/core/src/interface/simple_change.ts +++ b/packages/core/src/interface/simple_change.ts @@ -12,7 +12,6 @@ * {@link SimpleChanges} object to the `ngOnChanges` hook. * * @see {@link OnChanges} - * * @publicApi */ export class SimpleChange { @@ -31,7 +30,6 @@ export class SimpleChange { * the type passed to the `ngOnChanges` hook. * * @see {@link OnChanges} - * * @publicApi */ export interface SimpleChanges { diff --git a/packages/core/src/interface/type.ts b/packages/core/src/interface/type.ts index cbacc039ed4..46cb61b15fa 100644 --- a/packages/core/src/interface/type.ts +++ b/packages/core/src/interface/type.ts @@ -47,11 +47,13 @@ export type Mutable = { * * USAGE: * Given: + * * ``` * interface Person {readonly name: string} * ``` * * We would like to get a read/write version of `Person`. + * * ``` * const WritablePerson = Writable; * ``` @@ -66,6 +68,7 @@ export type Mutable = { * // Error: Correctly detects that `Person` did not have `age` property. * (readonlyPerson as WritablePerson).age = 30; * ``` + * */ export type Writable = { -readonly[K in keyof T]: T[K]; diff --git a/packages/core/src/linker/compiler.ts b/packages/core/src/linker/compiler.ts index 4b29838aa4d..a7bee7a4fa2 100644 --- a/packages/core/src/linker/compiler.ts +++ b/packages/core/src/linker/compiler.ts @@ -46,7 +46,6 @@ export class ModuleWithComponentFactories { * of components. * * @publicApi - * * @deprecated * Ivy JIT mode doesn't require accessing this symbol. * See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes) for @@ -71,6 +70,7 @@ export class Compiler { /** * Same as {@link #compileModuleSync} but also creates ComponentFactories for all components. + * */ compileModuleAndAllComponentsSync(moduleType: Type): ModuleWithComponentFactories { const ngModuleFactory = this.compileModuleSync(moduleType); @@ -87,6 +87,7 @@ export class Compiler { /** * Same as {@link #compileModuleAsync} but also creates ComponentFactories for all components. + * */ compileModuleAndAllComponentsAsync(moduleType: Type): Promise> { diff --git a/packages/core/src/linker/destroy_ref.ts b/packages/core/src/linker/destroy_ref.ts index 148a250d8ef..3128e9078e3 100644 --- a/packages/core/src/linker/destroy_ref.ts +++ b/packages/core/src/linker/destroy_ref.ts @@ -30,7 +30,9 @@ export abstract class DestroyRef { * be invoked to unregister the callback. * * @usageNotes + * * ### Example + * * ```typescript * const destroyRef = inject(DestroyRef); * @@ -40,6 +42,7 @@ export abstract class DestroyRef { * // stop the destroy callback from executing if needed * unregisterFn(); * ``` + * */ abstract onDestroy(callback: () => void): () => void; diff --git a/packages/core/src/linker/ng_module_factory_loader.ts b/packages/core/src/linker/ng_module_factory_loader.ts index 35b35824aaf..cbec24a8b82 100644 --- a/packages/core/src/linker/ng_module_factory_loader.ts +++ b/packages/core/src/linker/ng_module_factory_loader.ts @@ -16,6 +16,7 @@ import {getRegisteredNgModuleType} from './ng_module_registration'; * Returns the NgModuleFactory with the given id (specified using [@NgModule.id * field](api/core/NgModule#id)), if it exists and has been loaded. Factories for NgModules that do * not specify an `id` cannot be retrieved. Throws if an NgModule cannot be found. + * * @publicApi * @deprecated Use `getNgModuleById` instead. */ @@ -29,6 +30,7 @@ export function getModuleFactory(id: string): NgModuleFactory { * Returns the NgModule class with the given id (specified using [@NgModule.id * field](api/core/NgModule#id)), if it exists and has been loaded. Classes for NgModules that do * not specify an `id` cannot be retrieved. Throws if an NgModule cannot be found. + * * @publicApi */ export function getNgModuleById(id: string): Type { diff --git a/packages/core/src/linker/query_list.ts b/packages/core/src/linker/query_list.ts index 6302be80ef6..d490d272b65 100644 --- a/packages/core/src/linker/query_list.ts +++ b/packages/core/src/linker/query_list.ts @@ -33,14 +33,15 @@ function symbolIterator(this: QueryList): Iterator { * NOTE: In the future this class will implement an `Observable` interface. * * @usageNotes + * * ### Example + * * ```typescript * @Component({...}) * class Container { * @ViewChildren(Item) items:QueryList; * } * ``` - * * @publicApi */ export class QueryList implements Iterable { @@ -167,6 +168,7 @@ export class QueryList implements Iterable { /** * Triggers a change event by emitting on the `changes` {@link EventEmitter}. + * */ notifyOnChanges(): void { if (this._changes && (this._changesDetected || !this._emitDistinctChangesOnly)) diff --git a/packages/core/src/linker/view_container_ref.ts b/packages/core/src/linker/view_container_ref.ts index 158a4852769..5ec1cc0270d 100644 --- a/packages/core/src/linker/view_container_ref.ts +++ b/packages/core/src/linker/view_container_ref.ts @@ -139,9 +139,10 @@ export abstract class ViewContainerRef { * @param context The data-binding context of the embedded view, as declared * in the `` usage. * @param options Extra configuration for the created view. Includes: - * * index: The 0-based index at which to insert the new view into this container. - * If not specified, appends the new view as the last entry. - * * injector: Injector to be used within the embedded view. + * + * - index: The 0-based index at which to insert the new view into this container. + * If not specified, appends the new view as the last entry. + * - injector: Injector to be used within the embedded view. * * @returns The `ViewRef` instance for the newly created view. */ @@ -169,18 +170,19 @@ export abstract class ViewContainerRef { * * @param componentType Component Type to use. * @param options An object that contains extra parameters: - * * index: the index at which to insert the new component's host view into this container. - * If not specified, appends the new view as the last entry. - * * injector: the injector to use as the parent for the new component. - * * ngModuleRef: an NgModuleRef of the component's NgModule, you should almost always provide - * this to ensure that all expected providers are available for the component - * instantiation. - * * environmentInjector: an EnvironmentInjector which will provide the component's environment. - * you should almost always provide this to ensure that all expected providers - * are available for the component instantiation. This option is intended to - * replace the `ngModuleRef` parameter. - * * projectableNodes: list of DOM nodes that should be projected through - * [``](api/core/ng-content) of the new component instance. + * + * - index: the index at which to insert the new component's host view into this container. + * If not specified, appends the new view as the last entry. + * - injector: the injector to use as the parent for the new component. + * - ngModuleRef: an NgModuleRef of the component's NgModule, you should almost always provide + * this to ensure that all expected providers are available for the component + * instantiation. + * - environmentInjector: an EnvironmentInjector which will provide the component's environment. + * you should almost always provide this to ensure that all expected providers + * are available for the component instantiation. This option is intended to + * replace the `ngModuleRef` parameter. + * - projectableNodes: list of DOM nodes that should be projected through + * [``](api/core/ng-content) of the new component instance. * * @returns The new `ComponentRef` which contains the component instance and the host view. */ diff --git a/packages/core/src/metadata/di.ts b/packages/core/src/metadata/di.ts index 18aee5860c2..933cb498e6f 100644 --- a/packages/core/src/metadata/di.ts +++ b/packages/core/src/metadata/di.ts @@ -93,6 +93,7 @@ export abstract class Query {} export interface ContentChildrenDecorator { /** * @description + * * Property decorator that configures a content query. * * Use to get the `QueryList` of elements or directives from the content DOM. @@ -108,35 +109,36 @@ export interface ContentChildrenDecorator { * * * **selector** - The directive type or the name used for querying. * * **descendants** - If `true` include all descendants of the element. If `false` then only - * query direct children of the element. - * * **emitDistinctChangesOnly** - The ` QueryList#changes` observable will emit new values only + * query direct children of the element. + * * **emitDistinctChangesOnly** - The `QueryList#changes` observable will emit new values only * if the QueryList result has changed. When `false` the `changes` observable might emit even * if the QueryList has not changed. - * ** Note: *** This config option is **deprecated**, it will be permanently set to `true` and + * ** Note: \*** This config option is **deprecated**, it will be permanently set to `true` and * removed in future versions of Angular. * * **read** - Used to read a different token from the queried elements. * * The following selectors are supported. - * * Any class with the `@Component` or `@Directive` decorator - * * A template reference variable as a string (e.g. query `` - * with `@ContentChildren('cmp')`) - * * Any provider defined in the child component tree of the current component (e.g. - * `@ContentChildren(SomeService) someService: SomeService`) - * * Any provider defined through a string token (e.g. `@ContentChildren('someToken') - * someTokenVal: any`) - * * A `TemplateRef` (e.g. query `` with - * `@ContentChildren(TemplateRef) template;`) + * + * - Any class with the `@Component` or `@Directive` decorator + * - A template reference variable as a string (e.g. query `` + * with `@ContentChildren('cmp')`) + * - Any provider defined in the child component tree of the current component (e.g. + * `@ContentChildren(SomeService) someService: SomeService`) + * - Any provider defined through a string token (e.g. `@ContentChildren('someToken') + * someTokenVal: any`) + * - A `TemplateRef` (e.g. query `` with + * `@ContentChildren(TemplateRef) template;`) * * In addition, multiple string selectors can be separated with a comma (e.g. * `@ContentChildren('cmp1,cmp2')`) * * The following values are supported by `read`: - * * Any class with the `@Component` or `@Directive` decorator - * * Any provider defined on the injector of the component that is matched by the `selector` of - * this query - * * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) - * * `TemplateRef`, `ElementRef`, and `ViewContainerRef` * + * - Any class with the `@Component` or `@Directive` decorator + * - Any provider defined on the injector of the component that is matched by the `selector` of + * this query + * - Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) + * - `TemplateRef`, `ElementRef`, and `ViewContainerRef` * @usageNotes * * Here is a simple demonstration of how the `ContentChildren` decorator can be used. @@ -196,6 +198,7 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator( export interface ContentChildDecorator { /** * @description + * * Property decorator that configures a content query. * * Use to get the first element or the directive matching the selector from the content DOM. @@ -209,40 +212,42 @@ export interface ContentChildDecorator { * * * **selector** - The directive type or the name used for querying. * * **descendants** - If `true` (default) include all descendants of the element. If `false` then - * only query direct children of the element. + * only query direct children of the element. * * **read** - Used to read a different token from the queried element. * * **static** - True to resolve query results before change detection runs, - * false to resolve after change detection. Defaults to false. + * false to resolve after change detection. Defaults to false. * * The following selectors are supported. - * * Any class with the `@Component` or `@Directive` decorator - * * A template reference variable as a string (e.g. query `` - * with `@ContentChild('cmp')`) - * * Any provider defined in the child component tree of the current component (e.g. - * `@ContentChild(SomeService) someService: SomeService`) - * * Any provider defined through a string token (e.g. `@ContentChild('someToken') someTokenVal: - * any`) - * * A `TemplateRef` (e.g. query `` with `@ContentChild(TemplateRef) - * template;`) + * + * - Any class with the `@Component` or `@Directive` decorator + * - A template reference variable as a string (e.g. query `` + * with `@ContentChild('cmp')`) + * - Any provider defined in the child component tree of the current component (e.g. + * `@ContentChild(SomeService) someService: SomeService`) + * - Any provider defined through a string token (e.g. `@ContentChild('someToken') someTokenVal: + * any`) + * - A `TemplateRef` (e.g. query `` with `@ContentChild(TemplateRef) + * template;`) * * The following values are supported by `read`: - * * Any class with the `@Component` or `@Directive` decorator - * * Any provider defined on the injector of the component that is matched by the `selector` of - * this query - * * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) - * * `TemplateRef`, `ElementRef`, and `ViewContainerRef` + * + * - Any class with the `@Component` or `@Directive` decorator + * - Any provider defined on the injector of the component that is matched by the `selector` of + * this query + * - Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) + * - `TemplateRef`, `ElementRef`, and `ViewContainerRef` * * Difference between dynamic and static queries: * - * | Queries | Details | - * |:--- |:--- | - * | Dynamic queries \(`static: false`\) | The query resolves before the `ngAfterContentInit()` + * | Queries | Details | + * | :-------------------------------- | :--------------------------------------------------- | + * | Dynamic queries (`static: false`) | The query resolves before the `ngAfterContentInit()` | + * * callback is called. The result will be updated for changes to your view, such as changes to - * `ngIf` and `ngFor` blocks. | | Static queries \(`static: true`\) | The query resolves once + * `ngIf` and `ngFor` blocks. | | Static queries (`static: true`) | The query resolves once * the view has been created, but before change detection runs (before the `ngOnInit()` callback * is called). The result, though, will never be updated to reflect changes to your view, such as * changes to `ngIf` and `ngFor` blocks. | - * * @usageNotes * * {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'} @@ -290,6 +295,7 @@ export const ContentChild: ContentChildDecorator = makePropDecorator( export interface ViewChildrenDecorator { /** * @description + * * Property decorator that configures a view query. * * Use to get the `QueryList` of elements or directives from the view DOM. @@ -302,33 +308,34 @@ export interface ViewChildrenDecorator { * * * **selector** - The directive type or the name used for querying. * * **read** - Used to read a different token from the queried elements. - * * **emitDistinctChangesOnly** - The ` QueryList#changes` observable will emit new values only - * if the QueryList result has changed. When `false` the `changes` observable might emit even - * if the QueryList has not changed. - * ** Note: *** This config option is **deprecated**, it will be permanently set to `true` and - * removed in future versions of Angular. + * * **emitDistinctChangesOnly** - The `QueryList#changes` observable will emit new values only + * if the QueryList result has changed. When `false` the `changes` observable might emit even + * if the QueryList has not changed. + * ** Note: \*** This config option is **deprecated**, it will be permanently set to `true` and + * removed in future versions of Angular. * * The following selectors are supported. - * * Any class with the `@Component` or `@Directive` decorator - * * A template reference variable as a string (e.g. query `` - * with `@ViewChildren('cmp')`) - * * Any provider defined in the child component tree of the current component (e.g. - * `@ViewChildren(SomeService) someService!: SomeService`) - * * Any provider defined through a string token (e.g. `@ViewChildren('someToken') - * someTokenVal!: any`) - * * A `TemplateRef` (e.g. query `` with `@ViewChildren(TemplateRef) - * template;`) + * + * - Any class with the `@Component` or `@Directive` decorator + * - A template reference variable as a string (e.g. query `` + * with `@ViewChildren('cmp')`) + * - Any provider defined in the child component tree of the current component (e.g. + * `@ViewChildren(SomeService) someService!: SomeService`) + * - Any provider defined through a string token (e.g. `@ViewChildren('someToken') + * someTokenVal!: any`) + * - A `TemplateRef` (e.g. query `` with `@ViewChildren(TemplateRef) + * template;`) * * In addition, multiple string selectors can be separated with a comma (e.g. * `@ViewChildren('cmp1,cmp2')`) * * The following values are supported by `read`: - * * Any class with the `@Component` or `@Directive` decorator - * * Any provider defined on the injector of the component that is matched by the `selector` of - * this query - * * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) - * * `TemplateRef`, `ElementRef`, and `ViewContainerRef` * + * - Any class with the `@Component` or `@Directive` decorator + * - Any provider defined on the injector of the component that is matched by the `selector` of + * this query + * - Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) + * - `TemplateRef`, `ElementRef`, and `ViewContainerRef` * @usageNotes * * {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'} @@ -378,6 +385,7 @@ export const ViewChildren: ViewChildrenDecorator = makePropDecorator( export interface ViewChildDecorator { /** * @description + * * Property decorator that configures a view query. * The change detector looks for the first element or the directive matching the selector * in the view DOM. If the view DOM changes, and a new child matches the selector, @@ -388,38 +396,39 @@ export interface ViewChildDecorator { * * **selector** - The directive type or the name used for querying. * * **read** - Used to read a different token from the queried elements. * * **static** - `true` to resolve query results before change detection runs, - * `false` to resolve after change detection. Defaults to `false`. - * + * `false` to resolve after change detection. Defaults to `false`. * * The following selectors are supported. - * * Any class with the `@Component` or `@Directive` decorator - * * A template reference variable as a string (e.g. query `` - * with `@ViewChild('cmp')`) - * * Any provider defined in the child component tree of the current component (e.g. - * `@ViewChild(SomeService) someService: SomeService`) - * * Any provider defined through a string token (e.g. `@ViewChild('someToken') someTokenVal: - * any`) - * * A `TemplateRef` (e.g. query `` with `@ViewChild(TemplateRef) - * template;`) + * + * - Any class with the `@Component` or `@Directive` decorator + * - A template reference variable as a string (e.g. query `` + * with `@ViewChild('cmp')`) + * - Any provider defined in the child component tree of the current component (e.g. + * `@ViewChild(SomeService) someService: SomeService`) + * - Any provider defined through a string token (e.g. `@ViewChild('someToken') someTokenVal: + * any`) + * - A `TemplateRef` (e.g. query `` with `@ViewChild(TemplateRef) + * template;`) * * The following values are supported by `read`: - * * Any class with the `@Component` or `@Directive` decorator - * * Any provider defined on the injector of the component that is matched by the `selector` of - * this query - * * Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) - * * `TemplateRef`, `ElementRef`, and `ViewContainerRef` * - * Difference between dynamic and static queries**: + * - Any class with the `@Component` or `@Directive` decorator + * - Any provider defined on the injector of the component that is matched by the `selector` of + * this query + * - Any provider defined through a string token (e.g. `{provide: 'token', useValue: 'val'}`) + * - `TemplateRef`, `ElementRef`, and `ViewContainerRef` + * + * Difference between dynamic and static queries\*\*: + * + * | Queries | Details | + * | :-------------------------------- | :------------------------------------------------ | + * | Dynamic queries (`static: false`) | The query resolves before the `ngAfterViewInit()` | * - * | Queries | Details | - * |:--- |:--- | - * | Dynamic queries \(`static: false`\) | The query resolves before the `ngAfterViewInit()` * callback is called. The result will be updated for changes to your view, such as changes to - * `ngIf` and `ngFor` blocks. | | Static queries \(`static: true`\) | The query resolves once + * `ngIf` and `ngFor` blocks. | | Static queries (`static: true`) | The query resolves once * the view has been created, but before change detection runs (before the `ngOnInit()` callback * is called). The result, though, will never be updated to reflect changes to your view, such as * changes to `ngIf` and `ngFor` blocks. | - * * @usageNotes * * {@example core/di/ts/viewChild/view_child_example.ts region='Component'} diff --git a/packages/core/src/metadata/directives.ts b/packages/core/src/metadata/directives.ts index 53ef31a0964..ae00728b715 100644 --- a/packages/core/src/metadata/directives.ts +++ b/packages/core/src/metadata/directives.ts @@ -36,6 +36,7 @@ export interface DirectiveDecorator { * * * @usageNotes + * * To define a directive, mark the class with the decorator and provide metadata. * * ```ts @@ -53,8 +54,9 @@ export interface DirectiveDecorator { * * In order to make a directive available to other components in your application, you should do * one of the following: - * - either mark the directive as [standalone](guide/standalone-components), - * - or declare it in an NgModule by adding it to the `declarations` and `exports` fields. + * + * - either mark the directive as [standalone](guide/standalone-components), + * - or declare it in an NgModule by adding it to the `declarations` and `exports` fields. * * ** Marking a directive as standalone ** * @@ -72,7 +74,6 @@ export interface DirectiveDecorator { * When marking a directive as standalone, please make sure that the directive is not already * declared in an NgModule. * - * * ** Declaring a directive in an NgModule ** * * Another approach is to declare a directive in an NgModule: @@ -91,12 +92,12 @@ export interface DirectiveDecorator { * ``` * * When declaring a directive in an NgModule, please make sure that: - * - the directive is declared in exactly one NgModule. - * - the directive is not standalone. - * - you do not re-declare a directive imported from another module. - * - the directive is included into the `exports` field as well if you want this directive to be - * accessible for components outside of the NgModule. * + * - the directive is declared in exactly one NgModule. + * - the directive is not standalone. + * - you do not re-declare a directive imported from another module. + * - the directive is included into the `exports` field as well if you want this directive to be + * accessible for components outside of the NgModule. * * @Annotation */ @@ -314,12 +315,13 @@ export interface Directive { * is propagated to the specified property in the host element. * * For event handling: + * * - The key is the DOM event that the directive listens to. - * To listen to global events, add the target to the event name. - * The target can be `window`, `document` or `body`. + * To listen to global events, add the target to the event name. + * The target can be `window`, `document` or `body`. * - The value is the statement to execute when the event occurs. If the - * statement evaluates to `false`, then `preventDefault` is applied on the DOM - * event. A handler method can refer to the `$event` local variable. + * statement evaluates to `false`, then `preventDefault` is applied on the DOM + * event. A handler method can refer to the `$event` local variable. * */ host?: {[key: string]: string}; @@ -411,7 +413,6 @@ export interface ComponentDecorator { * * * - * * ### Setting component outputs * * The following example shows two event emitters that emit on an interval. One @@ -451,7 +452,6 @@ export interface ComponentDecorator { * }) * class HelloWorld { * } - * * ``` * * ### Preserving whitespace @@ -462,6 +462,7 @@ export interface ComponentDecorator { * the `preserveWhitespaces` option of the AOT compiler. * * By default, the AOT compiler removes whitespace characters as follows: + * * * Trims all whitespaces at the beginning and the end of a template. * * Removes whitespace-only text nodes. For example, * @@ -476,9 +477,9 @@ export interface ComponentDecorator { * ``` * * * Replaces a series of whitespace characters in text nodes with a single space. - * For example, `\n some text\n` becomes ` some text `. + * For example, `\n some text\n` becomes ` some text `. * * Does NOT alter text nodes inside HTML tags such as `
    ` or `