From 90a1155c4328e6a8850f5c46e85cf1e33beaafd8 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 14 Nov 2016 10:25:17 -0800 Subject: [PATCH] API doc comment updates for lifecycle hooks and router Contributes to #116. This is a followup to #124. This commit has updates for all remaining entries in the spreadsheet except for `CanActivate`, which I think should be handled once the router chapter is created. --- lib/src/core/metadata/lifecycle_hooks.dart | 286 ++++-------------- lib/src/router/directives/router_link.dart | 14 +- lib/src/router/directives/router_outlet.dart | 10 +- .../route_config/route_config_impl.dart | 10 +- 4 files changed, 72 insertions(+), 248 deletions(-) diff --git a/lib/src/core/metadata/lifecycle_hooks.dart b/lib/src/core/metadata/lifecycle_hooks.dart index 570a34e76..b7e3722b4 100644 --- a/lib/src/core/metadata/lifecycle_hooks.dart +++ b/lib/src/core/metadata/lifecycle_hooks.dart @@ -77,75 +77,33 @@ abstract class OnInit { /// Implement this interface to override the default change detection algorithm /// for your directive. /// -/// `ngDoCheck` gets called to check the changes in the directives instead of +/// [ngDoCheck] gets called to check the changes in the directives instead of /// the default algorithm. /// /// The default change detection algorithm looks for differences by comparing /// bound-property values by reference across change detection runs. When -/// `DoCheck` is implemented, the default algorithm is disabled and `ngDoCheck` +/// [DoCheck] is implemented, the default algorithm is disabled and [ngDoCheck] /// is responsible for checking for changes. /// /// Implementing this interface allows improving performance by using insights /// about the component, its implementation and data types of its properties. /// -/// Note that a directive should not implement both `DoCheck` and [OnChanges] at -/// the same time. `ngOnChanges` would not be called when a directive -/// implements `DoCheck`. Reaction to the changes have to be handled from within -/// the `ngDoCheck` callback. +/// Note that a directive should not implement both [DoCheck] and [OnChanges] at +/// the same time. [ngOnChanges] would not be called when a directive +/// implements [DoCheck]. Reaction to the changes have to be handled from within +/// the [ngDoCheck] callback. /// /// Use [KeyValueDiffers] and [IterableDiffers] to add your custom check /// mechanisms. /// -/// ### Example -/// -/// In the following example `ngDoCheck` uses an [IterableDiffers] to detect the -/// updates to the array `list`: -/// -/// ```dart -/// @Component( -/// selector: 'custom-check', -/// template: ''' -///

Changes:

-/// -/// ''', -/// directives: const [NgFor] -/// ) -/// class CustomCheckComponent implements DoCheck { -/// final IterableDiffer differ; -/// final List logs = []; -/// -/// @Input() -/// List list; -/// -/// CustomCheckComponent(IterableDiffers differs) : -/// differ = differs.find([]).create(null); -/// -/// @override -/// ngDoCheck() { -/// var changes = differ.diff(list); -/// -/// if (changes is DefaultIterableDiffer) { -/// changes.forEachAddedItem(r => logs.add('added ${r.item}')); -/// changes.forEachRemovedItem(r => logs.add('removed ${r.item}')) -/// } -/// } -/// } -/// -/// @Component({ -/// selector: 'app', -/// template: ''' -/// -/// -/// -/// ''', -/// directives: const [CustomCheckComponent] -/// }) -/// class App { -/// List list = []; -/// } -/// ``` +/// ### Examples +/// +/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page: +/// +/// {@example docs/lifecycle-hooks/lib/do_check_component.dart region=ng-do-check} +/// +/// [docs]: docs/guide/lifecycle-hooks.html#docheck +/// [ex]: examples/lifecycle-hooks#docheck abstract class DoCheck { ngDoCheck(); } @@ -170,52 +128,16 @@ abstract class OnDestroy { /// Implement this interface to get notified when your directive's content has /// been fully initialized. /// -/// ### Example -/// -/// ```dart -/// @Component( -/// selector: 'child-cmp', -/// template: '{{where}} child' -/// ) -/// class ChildComponent { -/// @Input() -/// String where; -/// } -/// -/// @Component( -/// selector: 'parent-cmp', -/// template: '' -/// ) -/// class ParentComponent implements AfterContentInit { -/// @ContentChild(ChildComponent) -/// ChildComponent contentChild;; -/// -/// ParentComponent() { -/// // contentChild is not initialized yet -/// print(_message(contentChild)); -/// } -/// -/// @override -/// ngAfterContentInit() { -/// // contentChild is updated after the content has been checked -/// print('AfterContentInit: ' + _message(contentChild)); -/// } -/// -/// String _message(ChildComponent cmp) => -/// cmp == null ? 'no child' : '${cmp.where} child'; -/// } -/// -/// @Component( -/// selector: 'app', -/// template: ''' -/// -/// -/// -/// ''', -/// directives: const [ParentComponent, ChildComponent] -/// ) -/// class App {} -/// ``` +/// ### Examples +/// +/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page: +/// +/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=template} +/// +/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=hooks} +/// +/// [docs]: docs/guide/lifecycle-hooks.html#aftercontent +/// [ex]: examples/lifecycle-hooks#after-content abstract class AfterContentInit { ngAfterContentInit(); } @@ -223,51 +145,16 @@ abstract class AfterContentInit { /// Implement this interface to get notified after every check of your /// directive's content. /// -/// ### Example -/// -/// ```dart -/// @Component(selector: 'child-cmp', template: '{{where}} child') -/// class ChildComponent { -/// @Input() -/// String where; -/// } -/// -/// @Component(selector: 'parent-cmp', template: '') -/// class ParentComponent implements AfterContentChecked { -/// @ContentChild(ChildComponent) -/// ChildComponent contentChild; -/// -/// ParentComponent() { -/// // contentChild is not initialized yet -/// print(_message(contentChild)); -/// } -/// -/// @override -/// ngAfterContentChecked() { -/// // contentChild is updated after the content has been checked -/// print('AfterContentChecked: ${_message(contentChild)}'); -/// } -/// -/// String _message(ChildComponent cmp) => -/// cmp == null ? 'no child' : '${cmp.where} child'; -/// } -/// -/// @Component( -/// selector: 'app', -/// template: ''' -/// -/// -/// -/// -/// ''', -/// directives: const [NgIf, ParentComponent, ChildComponent] -/// ) -/// class App { -/// bool hasContent = true; -/// } -/// ``` +/// ### Examples +/// +/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page: +/// +/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=template} +/// +/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=hooks} +/// +/// [docs]: docs/guide/lifecycle-hooks.html#aftercontent +/// [ex]: examples/lifecycle-hooks#after-content abstract class AfterContentChecked { ngAfterContentChecked(); } @@ -275,46 +162,16 @@ abstract class AfterContentChecked { /// Implement this interface to get notified when your component's view has been /// fully initialized. /// -/// ### Example -/// -/// ```dart -/// @Component(selector: 'child-cmp', template: '{{where}} child') -/// class ChildComponent { -/// @Input() -/// String where; -/// } -/// -/// @Component( -/// selector: 'parent-cmp', -/// template: '', -/// directives: const [ChildComponent] -/// ) -/// class ParentComponent implements AfterViewInit { -/// @ViewChild(ChildComponent) -/// ChildComponent viewChild; -/// -/// ParentComponent() { -/// // viewChild is not initialized yet -/// print(_message(viewChild)); -/// } -/// -/// @override -/// ngAfterViewInit() { -/// // viewChild is updated after the view has been initialized -/// print('ngAfterViewInit: ' + _message(viewChild)); -/// } -/// -/// String _message(ChildComponent cmp) => -/// cmp == null ? 'no child' : '${cmp.where} child'; -/// } -/// -/// @Component( -/// selector: 'app', -/// template: '', -/// directives: const [ParentComponent] -/// ) -/// class App {} -/// ``` +/// ### Examples +/// +/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page: +/// +/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=template} +/// +/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=hooks} +/// +/// [docs]: docs/guide/lifecycle-hooks.html#afterview +/// [ex]: examples/lifecycle-hooks#after-view abstract class AfterViewInit { ngAfterViewInit(); } @@ -322,51 +179,16 @@ abstract class AfterViewInit { /// Implement this interface to get notified after every check of your /// component's view. /// -/// ### Example -/// -/// ```dart -/// @Component(selector: 'child-cmp', template: '{{where}} child') -/// class ChildComponent { -/// @Input() -/// String where; -/// } -/// -/// @Component( -/// selector: 'parent-cmp', -/// template: ''' -/// -/// -/// ''', -/// directives: const [NgIf, ChildComponent] -/// ) -/// class ParentComponent implements AfterViewChecked { -/// @ViewChild(ChildComponent) -/// ChildComponent viewChild; -/// -/// bool showView = true; -/// -/// ParentComponent() { -/// // viewChild is not initialized yet -/// print(_message(viewChild)); -/// } -/// -/// @override -/// ngAfterViewChecked() { -/// // viewChild is updated after the view has been checked -/// print('AfterViewChecked: ${_message(viewChild)}'); -/// } -/// -/// String _message(ChildComponent cmp) => -/// cmp == null ? 'no child' : '${cmp.where} child'; -/// } -/// -/// @Component( -/// selector: 'app', -/// template: '', -/// directives: const [ParentComponent] -/// ) -/// class App {} -/// ``` +/// ### Examples +/// +/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page: +/// +/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=template} +/// +/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=hooks} +/// +/// [docs]: docs/guide/lifecycle-hooks.html#afterview +/// [ex]: examples/lifecycle-hooks#after-view abstract class AfterViewChecked { ngAfterViewChecked(); } diff --git a/lib/src/router/directives/router_link.dart b/lib/src/router/directives/router_link.dart index 1f8b1d2f0..d70152965 100644 --- a/lib/src/router/directives/router_link.dart +++ b/lib/src/router/directives/router_link.dart @@ -7,18 +7,12 @@ import "../router.dart" show Router; /// The RouterLink directive lets you link to specific parts of your app. /// /// Consider the following route configuration: -/// ``` -/// @RouteConfig([ -/// { path: '/user', component: UserCmp, as: 'User' } -/// ]); -/// class MyComp {} -/// ``` /// -/// When linking to this `User` route, you can write: +/// {@example docs/toh-5/lib/app_component.dart region=heroes} /// -/// ``` -/// link to user component -/// ``` +/// When linking to this `Heroes` route, you can write: +/// +/// {@example docs/toh-5/lib/app_component_1.dart region=template-v2} /// /// RouterLink expects the value to be an array of route names, followed by the params /// for that level of routing. For instance `['/Team', {teamId: 1}, 'User', {userId: 2}]` diff --git a/lib/src/router/directives/router_outlet.dart b/lib/src/router/directives/router_outlet.dart index 5ac189f3c..d891e71fb 100644 --- a/lib/src/router/directives/router_outlet.dart +++ b/lib/src/router/directives/router_outlet.dart @@ -25,11 +25,13 @@ var _resolveToTrue = new Future.value(true); /// A router outlet is a placeholder that Angular dynamically fills based on the application's route. /// -/// ## Use +/// ### Example /// -/// ``` -/// -/// ``` +/// Here is an example from the [tutorial on routing][routing]: +/// +/// {@example docs/toh-5/lib/app_component.dart region=template} +/// +/// [routing]: docs/tutorial/toh-pt5.html#router-outlet @Directive(selector: "router-outlet") class RouterOutlet implements OnDestroy { ViewContainerRef _viewContainerRef; diff --git a/lib/src/router/route_config/route_config_impl.dart b/lib/src/router/route_config/route_config_impl.dart index f4cc3a27b..7e513261c 100644 --- a/lib/src/router/route_config/route_config_impl.dart +++ b/lib/src/router/route_config/route_config_impl.dart @@ -7,9 +7,15 @@ export "../route_definition.dart" show RouteDefinition; Future ___make_dart_analyzer_happy; -/// The `RouteConfig` decorator defines routes for a given component. +/// The [RouteConfig] decorator defines routes for a given component. /// -/// It takes an array of [RouteDefinition]s. +/// ### Example +/// +/// Here is an example from the [tutorial on routing][routing]: +/// +/// {@example docs/toh-5/lib/app_component.dart region=routes} +/// +/// [routing]: docs/tutorial/toh-pt5.html#configure-routes class RouteConfig { final List configs; const RouteConfig(this.configs);