Skip to content

Commit 90a1155

Browse files
chalinchalin
committed
API doc comment updates for lifecycle hooks and router
Contributes to angulardart#116. This is a followup to angulardart#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.
1 parent 48eb99b commit 90a1155

File tree

4 files changed

+72
-248
lines changed

4 files changed

+72
-248
lines changed

‎lib/src/core/metadata/lifecycle_hooks.dart‎

Lines changed: 54 additions & 232 deletions
Original file line numberDiff line numberDiff line change
@@ -77,75 +77,33 @@ abstract class OnInit {
7777
/// Implement this interface to override the default change detection algorithm
7878
/// for your directive.
7979
///
80-
/// `ngDoCheck` gets called to check the changes in the directives instead of
80+
/// [ngDoCheck] gets called to check the changes in the directives instead of
8181
/// the default algorithm.
8282
///
8383
/// The default change detection algorithm looks for differences by comparing
8484
/// bound-property values by reference across change detection runs. When
85-
/// `DoCheck` is implemented, the default algorithm is disabled and `ngDoCheck`
85+
/// [DoCheck] is implemented, the default algorithm is disabled and [ngDoCheck]
8686
/// is responsible for checking for changes.
8787
///
8888
/// Implementing this interface allows improving performance by using insights
8989
/// about the component, its implementation and data types of its properties.
9090
///
91-
/// Note that a directive should not implement both `DoCheck` and [OnChanges] at
92-
/// the same time. `ngOnChanges` would not be called when a directive
93-
/// implements `DoCheck`. Reaction to the changes have to be handled from within
94-
/// the `ngDoCheck` callback.
91+
/// Note that a directive should not implement both [DoCheck] and [OnChanges] at
92+
/// the same time. [ngOnChanges] would not be called when a directive
93+
/// implements [DoCheck]. Reaction to the changes have to be handled from within
94+
/// the [ngDoCheck] callback.
9595
///
9696
/// Use [KeyValueDiffers] and [IterableDiffers] to add your custom check
9797
/// mechanisms.
9898
///
99-
/// ### Example
100-
///
101-
/// In the following example `ngDoCheck` uses an [IterableDiffers] to detect the
102-
/// updates to the array `list`:
103-
///
104-
/// ```dart
105-
/// @Component(
106-
/// selector: 'custom-check',
107-
/// template: '''
108-
/// <p>Changes:</p>
109-
/// <ul>
110-
/// <li *ngFor="let line of logs">{{line}}</li>
111-
/// </ul>
112-
/// ''',
113-
/// directives: const [NgFor]
114-
/// )
115-
/// class CustomCheckComponent implements DoCheck {
116-
/// final IterableDiffer differ;
117-
/// final List<String> logs = [];
118-
///
119-
/// @Input()
120-
/// List list;
121-
///
122-
/// CustomCheckComponent(IterableDiffers differs) :
123-
/// differ = differs.find([]).create(null);
124-
///
125-
/// @override
126-
/// ngDoCheck() {
127-
/// var changes = differ.diff(list);
128-
///
129-
/// if (changes is DefaultIterableDiffer) {
130-
/// changes.forEachAddedItem(r => logs.add('added ${r.item}'));
131-
/// changes.forEachRemovedItem(r => logs.add('removed ${r.item}'))
132-
/// }
133-
/// }
134-
/// }
135-
///
136-
/// @Component({
137-
/// selector: 'app',
138-
/// template: '''
139-
/// <button (click)="list.push(list.length)">Push</button>
140-
/// <button (click)="list.pop()">Pop</button>
141-
/// <custom-check [list]="list"></custom-check>
142-
/// ''',
143-
/// directives: const [CustomCheckComponent]
144-
/// })
145-
/// class App {
146-
/// List list = [];
147-
/// }
148-
/// ```
99+
/// ### Examples
100+
///
101+
/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page:
102+
///
103+
/// {@example docs/lifecycle-hooks/lib/do_check_component.dart region=ng-do-check}
104+
///
105+
/// [docs]: docs/guide/lifecycle-hooks.html#docheck
106+
/// [ex]: examples/lifecycle-hooks#docheck
149107
abstract class DoCheck {
150108
ngDoCheck();
151109
}
@@ -170,203 +128,67 @@ abstract class OnDestroy {
170128
/// Implement this interface to get notified when your directive's content has
171129
/// been fully initialized.
172130
///
173-
/// ### Example
174-
///
175-
/// ```dart
176-
/// @Component(
177-
/// selector: 'child-cmp',
178-
/// template: '{{where}} child'
179-
/// )
180-
/// class ChildComponent {
181-
/// @Input()
182-
/// String where;
183-
/// }
184-
///
185-
/// @Component(
186-
/// selector: 'parent-cmp',
187-
/// template: '<ng-content></ng-content>'
188-
/// )
189-
/// class ParentComponent implements AfterContentInit {
190-
/// @ContentChild(ChildComponent)
191-
/// ChildComponent contentChild;;
192-
///
193-
/// ParentComponent() {
194-
/// // contentChild is not initialized yet
195-
/// print(_message(contentChild));
196-
/// }
197-
///
198-
/// @override
199-
/// ngAfterContentInit() {
200-
/// // contentChild is updated after the content has been checked
201-
/// print('AfterContentInit: ' + _message(contentChild));
202-
/// }
203-
///
204-
/// String _message(ChildComponent cmp) =>
205-
/// cmp == null ? 'no child' : '${cmp.where} child';
206-
/// }
207-
///
208-
/// @Component(
209-
/// selector: 'app',
210-
/// template: '''
211-
/// <parent-cmp>
212-
/// <child-cmp where="content"></child-cmp>
213-
/// </parent-cmp>
214-
/// ''',
215-
/// directives: const [ParentComponent, ChildComponent]
216-
/// )
217-
/// class App {}
218-
/// ```
131+
/// ### Examples
132+
///
133+
/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page:
134+
///
135+
/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=template}
136+
///
137+
/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=hooks}
138+
///
139+
/// [docs]: docs/guide/lifecycle-hooks.html#aftercontent
140+
/// [ex]: examples/lifecycle-hooks#after-content
219141
abstract class AfterContentInit {
220142
ngAfterContentInit();
221143
}
222144

223145
/// Implement this interface to get notified after every check of your
224146
/// directive's content.
225147
///
226-
/// ### Example
227-
///
228-
/// ```dart
229-
/// @Component(selector: 'child-cmp', template: '{{where}} child')
230-
/// class ChildComponent {
231-
/// @Input()
232-
/// String where;
233-
/// }
234-
///
235-
/// @Component(selector: 'parent-cmp', template: '<ng-content></ng-content>')
236-
/// class ParentComponent implements AfterContentChecked {
237-
/// @ContentChild(ChildComponent)
238-
/// ChildComponent contentChild;
239-
///
240-
/// ParentComponent() {
241-
/// // contentChild is not initialized yet
242-
/// print(_message(contentChild));
243-
/// }
244-
///
245-
/// @override
246-
/// ngAfterContentChecked() {
247-
/// // contentChild is updated after the content has been checked
248-
/// print('AfterContentChecked: ${_message(contentChild)}');
249-
/// }
250-
///
251-
/// String _message(ChildComponent cmp) =>
252-
/// cmp == null ? 'no child' : '${cmp.where} child';
253-
/// }
254-
///
255-
/// @Component(
256-
/// selector: 'app',
257-
/// template: '''
258-
/// <parent-cmp>
259-
/// <button (click)="hasContent = !hasContent">
260-
/// Toggle content child
261-
/// </button>
262-
/// <child-cmp *ngIf="hasContent" where="content"></child-cmp>
263-
/// </parent-cmp>
264-
/// ''',
265-
/// directives: const [NgIf, ParentComponent, ChildComponent]
266-
/// )
267-
/// class App {
268-
/// bool hasContent = true;
269-
/// }
270-
/// ```
148+
/// ### Examples
149+
///
150+
/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page:
151+
///
152+
/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=template}
153+
///
154+
/// {@example docs/lifecycle-hooks/lib/after_content_component.dart region=hooks}
155+
///
156+
/// [docs]: docs/guide/lifecycle-hooks.html#aftercontent
157+
/// [ex]: examples/lifecycle-hooks#after-content
271158
abstract class AfterContentChecked {
272159
ngAfterContentChecked();
273160
}
274161

275162
/// Implement this interface to get notified when your component's view has been
276163
/// fully initialized.
277164
///
278-
/// ### Example
279-
///
280-
/// ```dart
281-
/// @Component(selector: 'child-cmp', template: '{{where}} child')
282-
/// class ChildComponent {
283-
/// @Input()
284-
/// String where;
285-
/// }
286-
///
287-
/// @Component(
288-
/// selector: 'parent-cmp',
289-
/// template: '<child-cmp where="view"></child-cmp>',
290-
/// directives: const [ChildComponent]
291-
/// )
292-
/// class ParentComponent implements AfterViewInit {
293-
/// @ViewChild(ChildComponent)
294-
/// ChildComponent viewChild;
295-
///
296-
/// ParentComponent() {
297-
/// // viewChild is not initialized yet
298-
/// print(_message(viewChild));
299-
/// }
300-
///
301-
/// @override
302-
/// ngAfterViewInit() {
303-
/// // viewChild is updated after the view has been initialized
304-
/// print('ngAfterViewInit: ' + _message(viewChild));
305-
/// }
306-
///
307-
/// String _message(ChildComponent cmp) =>
308-
/// cmp == null ? 'no child' : '${cmp.where} child';
309-
/// }
310-
///
311-
/// @Component(
312-
/// selector: 'app',
313-
/// template: '<parent-cmp></parent-cmp>',
314-
/// directives: const [ParentComponent]
315-
/// )
316-
/// class App {}
317-
/// ```
165+
/// ### Examples
166+
///
167+
/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page:
168+
///
169+
/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=template}
170+
///
171+
/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=hooks}
172+
///
173+
/// [docs]: docs/guide/lifecycle-hooks.html#afterview
174+
/// [ex]: examples/lifecycle-hooks#after-view
318175
abstract class AfterViewInit {
319176
ngAfterViewInit();
320177
}
321178

322179
/// Implement this interface to get notified after every check of your
323180
/// component's view.
324181
///
325-
/// ### Example
326-
///
327-
/// ```dart
328-
/// @Component(selector: 'child-cmp', template: '{{where}} child')
329-
/// class ChildComponent {
330-
/// @Input()
331-
/// String where;
332-
/// }
333-
///
334-
/// @Component(
335-
/// selector: 'parent-cmp',
336-
/// template: '''
337-
/// <button (click)="showView = !showView">Toggle view child</button>
338-
/// <child-cmp *ngIf="showView" where="view"></child-cmp>
339-
/// ''',
340-
/// directives: const [NgIf, ChildComponent]
341-
/// )
342-
/// class ParentComponent implements AfterViewChecked {
343-
/// @ViewChild(ChildComponent)
344-
/// ChildComponent viewChild;
345-
///
346-
/// bool showView = true;
347-
///
348-
/// ParentComponent() {
349-
/// // viewChild is not initialized yet
350-
/// print(_message(viewChild));
351-
/// }
352-
///
353-
/// @override
354-
/// ngAfterViewChecked() {
355-
/// // viewChild is updated after the view has been checked
356-
/// print('AfterViewChecked: ${_message(viewChild)}');
357-
/// }
358-
///
359-
/// String _message(ChildComponent cmp) =>
360-
/// cmp == null ? 'no child' : '${cmp.where} child';
361-
/// }
362-
///
363-
/// @Component(
364-
/// selector: 'app',
365-
/// template: '<parent-cmp></parent-cmp>',
366-
/// directives: const [ParentComponent]
367-
/// )
368-
/// class App {}
369-
/// ```
182+
/// ### Examples
183+
///
184+
/// Try this [live example][ex] from the [Lifecycle Hooks][docs] page:
185+
///
186+
/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=template}
187+
///
188+
/// {@example docs/lifecycle-hooks/lib/after_view_component.dart region=hooks}
189+
///
190+
/// [docs]: docs/guide/lifecycle-hooks.html#afterview
191+
/// [ex]: examples/lifecycle-hooks#after-view
370192
abstract class AfterViewChecked {
371193
ngAfterViewChecked();
372194
}

‎lib/src/router/directives/router_link.dart‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,12 @@ import "../router.dart" show Router;
77
/// The RouterLink directive lets you link to specific parts of your app.
88
///
99
/// Consider the following route configuration:
10-
/// ```
11-
/// @RouteConfig([
12-
/// { path: '/user', component: UserCmp, as: 'User' }
13-
/// ]);
14-
/// class MyComp {}
15-
/// ```
1610
///
17-
/// When linking to this `User` route, you can write:
11+
/// {@example docs/toh-5/lib/app_component.dart region=heroes}
1812
///
19-
/// ```
20-
/// <a [routerLink]="['./User']">link to user component</a>
21-
/// ```
13+
/// When linking to this `Heroes` route, you can write:
14+
///
15+
/// {@example docs/toh-5/lib/app_component_1.dart region=template-v2}
2216
///
2317
/// RouterLink expects the value to be an array of route names, followed by the params
2418
/// for that level of routing. For instance `['/Team', {teamId: 1}, 'User', {userId: 2}]`

‎lib/src/router/directives/router_outlet.dart‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,13 @@ var _resolveToTrue = new Future.value(true);
2525

2626
/// A router outlet is a placeholder that Angular dynamically fills based on the application's route.
2727
///
28-
/// ## Use
28+
/// ### Example
2929
///
30-
/// ```
31-
/// <router-outlet></router-outlet>
32-
/// ```
30+
/// Here is an example from the [tutorial on routing][routing]:
31+
///
32+
/// {@example docs/toh-5/lib/app_component.dart region=template}
33+
///
34+
/// [routing]: docs/tutorial/toh-pt5.html#router-outlet
3335
@Directive(selector: "router-outlet")
3436
class RouterOutlet implements OnDestroy {
3537
ViewContainerRef _viewContainerRef;

‎lib/src/router/route_config/route_config_impl.dart‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,15 @@ export "../route_definition.dart" show RouteDefinition;
77

88
Future<dynamic> ___make_dart_analyzer_happy;
99

10-
/// The `RouteConfig` decorator defines routes for a given component.
10+
/// The [RouteConfig] decorator defines routes for a given component.
1111
///
12-
/// It takes an array of [RouteDefinition]s.
12+
/// ### Example
13+
///
14+
/// Here is an example from the [tutorial on routing][routing]:
15+
///
16+
/// {@example docs/toh-5/lib/app_component.dart region=routes}
17+
///
18+
/// [routing]: docs/tutorial/toh-pt5.html#configure-routes
1319
class RouteConfig {
1420
final List<RouteDefinition> configs;
1521
const RouteConfig(this.configs);

0 commit comments

Comments
 (0)