Skip to content

Commit 7900d69

Browse files
ykmnkmiykmnkmi
committed
ngrouter: update comments.
1 parent 778898f commit 7900d69

16 files changed

+158
-83
lines changed

‎ngrouter/lib/src/constants.dart‎

Lines changed: 34 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,10 @@ import 'router/router_impl.dart';
1111
///
1212
/// Attach to a @[Component]'s directives when using any other the Router
1313
/// directives.
14-
/// ```
14+
/// ```dart
1515
/// @Component(
1616
/// selector: 'my-app',
17-
/// directives: [routerDirectives]
17+
/// directives: const [routerDirectives]
1818
/// template: '<router-outlet></router-outlet>'
1919
/// )
2020
/// class MyApp {}
@@ -24,11 +24,15 @@ const routerDirectives = [RouterOutlet, RouterLink, RouterLinkActive];
2424
/// The main [Router] providers.
2525
///
2626
/// The [routerProviders] should be added to the app's root injector.
27-
/// ```
28-
/// @GenerateInjector([routerProviders])
27+
/// ```dart
28+
/// @GenerateInjector(const [
29+
/// routerProviders,
30+
/// ])
2931
/// final InjectorFactory appInjector = ng.appInjector$Injector;
30-
/// ...
31-
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
32+
///
33+
/// void main() {
34+
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
35+
/// }
3236
/// ```
3337
const routerProviders = [
3438
ClassProvider(LocationStrategy, useClass: PathLocationStrategy),
@@ -40,22 +44,30 @@ const routerProviders = [
4044
/// The main [Router] DI module.
4145
///
4246
/// The [routerModule] should be added to the app's root injector.
43-
/// ```
44-
/// @GenerateInjector.fromModules([routerModule])
47+
/// ```dart
48+
/// @GenerateInjector.fromModules(const [
49+
/// routerModule
50+
/// ])
4551
/// final InjectorFactory appInjector = ng.appInjector$Injector;
46-
/// ...
47-
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
52+
///
53+
/// void main() {
54+
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
55+
/// }
4856
/// ```
4957
const routerModule = Module(provide: routerProviders);
5058

5159
/// The main [Router] providers when using hash routing.
5260
///
5361
/// The [routerProvidersHash] should be added to the app's root injector.
54-
/// ```
55-
/// @GenerateInjector([routerProvidersHash])
62+
/// ```dart
63+
/// @GenerateInjector(const [
64+
/// routerProvidersHash
65+
/// ])
5666
/// final InjectorFactory appInjector = ng.appInjector$Injector;
57-
/// ...
58-
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
67+
///
68+
/// void main() {
69+
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
70+
/// }
5971
/// ```
6072
const routerProvidersHash = [
6173
ClassProvider(LocationStrategy, useClass: HashLocationStrategy),
@@ -67,10 +79,14 @@ const routerProvidersHash = [
6779
/// The main [Router] DI module when using hash routing.
6880
///
6981
/// The [routerHashModule] should be added to the app's root injector.
70-
/// ```
71-
/// @GenerateInjector.fromModules([routerHashModule])
82+
/// ```dart
83+
/// @GenerateInjector.fromModules(const [
84+
/// routerHashModule
85+
/// ])
7286
/// final InjectorFactory appInjector = ng.appInjector$Injector;
73-
/// ...
74-
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
87+
///
88+
/// void main() {
89+
/// runApp(ng.MyAppComponentNgFactory, createInjector: appInjector);
90+
/// }
7591
/// ```
7692
const routerHashModule = Module(provide: routerProvidersHash);

‎ngrouter/lib/src/directives/router_link_directive.dart‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
/// @docImport '../route_path.dart';
2+
library;
3+
14
import 'dart:async';
25
import 'dart:html'
36
show AnchorElement, Element, Event, KeyboardEvent, KeyCode, MouseEvent;
@@ -14,7 +17,7 @@ import '../url.dart';
1417
/// ```html
1518
/// <a routerLink="/heroes">Heroes</a>
1619
/// ```
17-
/// Can also be used with [RouterPath].
20+
/// Can also be used with [RoutePath].
1821
/// ```html
1922
/// <a [routerLink]="heroPath.toUrl()">Heroes</a>
2023
/// ```

‎ngrouter/lib/src/lifecycle.dart‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ abstract class CanActivate {
2323
///
2424
/// You can use `async` in order to simplify when returning synchronously:
2525
///
26-
/// ```
26+
/// ```dart
2727
/// class MyComponent implements CanActivate {
2828
/// @override
29-
/// Future<bool> canActivate(RouterState _, RouterState __) async {
29+
/// Future<bool> canActivate(RouterState current, RouterState next) async {
3030
/// // Maybe this page isn't ready yet for production, so always reject.
3131
/// return false;
3232
/// }
@@ -59,14 +59,15 @@ abstract class CanDeactivate {
5959
/// accept the transition, or completes with `false` in order to reject it
6060
/// (and prevent the routing from occurring).
6161
///
62-
/// ```
62+
/// ```dart
6363
/// class MyComponent implements CanDeactivate {
6464
/// @override
6565
/// Future<bool> canDeactivate(
6666
/// RouterState current,
6767
/// RouterState next,
68-
/// ) async =>
69-
/// current.parameters['id'] != next.parameters['id'];
68+
/// ) async {
69+
/// return current.parameters['id'] != next.parameters['id'];
70+
/// }
7071
/// }
7172
/// ```
7273
///
@@ -93,7 +94,7 @@ abstract class CanNavigate {
9394
/// The client should return a future that completes with a boolean indicating
9495
/// whether the router is allowed to navigate.
9596
///
96-
/// ```
97+
/// ```dart
9798
/// class MyComponent implements CanNavigate {
9899
/// bool get _hasFormBeenSaved => ...;
99100
///
@@ -122,7 +123,7 @@ abstract class CanReuse {
122123
///
123124
/// You can use `async` in order to simplify when returning synchronously:
124125
///
125-
/// ```
126+
/// ```dart
126127
/// class MyComponent implements CanReuse {
127128
/// @override
128129
/// Future<bool> canReuse(RouterState current, RouterState next) async {
@@ -134,7 +135,7 @@ abstract class CanReuse {
134135
///
135136
/// Or simply mixin or extend this class:
136137
///
137-
/// ```
138+
/// ```dart
138139
/// class MyComponent extends CanReuse {}
139140
/// ```
140141
Future<bool> canReuse(RouterState current, RouterState next) async {
@@ -158,10 +159,10 @@ abstract class OnActivate {
158159
///
159160
/// ```dart
160161
/// class MyComponent extends CanReuse implements OnActivate {
161-
/// User user;
162+
/// late User user;
162163
///
163164
/// @override
164-
/// void onActivate(_, RouterState current) {
165+
/// void onActivate(RouterState? previous, RouterState current) {
165166
/// var userId = current.getParameter('userId');
166167
/// getUserById(userId).then((user) => this.user = user);
167168
/// }

‎ngrouter/lib/src/location/hash_location_strategy.dart‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,14 @@ import 'platform_location.dart' show PlatformLocation;
1616
///
1717
/// ### Example
1818
///
19-
/// ```
19+
/// ```dart
2020
/// import 'package:ngdart/angular.dart';
2121
/// import 'package:ngrouter/ngrouter.dart';
2222
///
2323
/// @Component(
2424
/// // Should only be provided at the root.
25-
/// providers: [
26-
/// routerProvidersHash,
25+
/// providers: const [
26+
/// routerProvidersHash
2727
/// ],
2828
/// )
2929
/// class AppComponent {

‎ngrouter/lib/src/location/location.dart‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,13 @@ import 'location_strategy.dart' show LocationStrategy;
2323
///
2424
/// ### Example
2525
///
26-
/// ```
26+
/// ```dart
2727
/// import 'package:ngdart/angular.dart';
2828
/// import 'package:ngrouter/ngrouter.dart';
2929
///
3030
/// @Component(
3131
/// // Should only be provided at the root.
32-
/// providers: [routerProviders],
32+
/// providers: const [routerProviders],
3333
/// )
3434
/// class AppComponent {
3535
/// AppComponent(Location location) {

‎ngrouter/lib/src/location/location_strategy.dart‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/// @docImport '../router/router.dart';
2+
/// @docImport 'hash_location_strategy.dart';
3+
/// @docImport 'path_location_strategy.dart';
4+
library;
5+
16
import 'dart:html';
27

38
import 'package:ngdart/angular.dart' show OpaqueToken;

‎ngrouter/lib/src/location/path_location_strategy.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
/// @docImport '../constants.dart';
2+
library;
3+
14
import 'dart:html' as html;
25

36
import 'package:ngdart/angular.dart' show Injectable, Inject, Optional;

‎ngrouter/lib/src/location/platform_location.dart‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/// @docImport '../router/router.dart';
2+
/// @docImport 'location_strategy.dart';
3+
library;
4+
15
import 'dart:html';
26

37
/// This class should not be used directly by an application developer. Instead, use
@@ -8,8 +12,7 @@ import 'dart:html';
812
/// This means that we can have different implementation of `PlatformLocation` for the different
913
/// platforms
1014
/// that angular supports. For example, the default `PlatformLocation` is {@link
11-
/// BrowserPlatformLocation},
12-
/// however when you run your app in a WebWorker you use [WebWorkerPlatformLocation].
15+
/// BrowserPlatformLocation}.
1316
///
1417
/// The `PlatformLocation` class is used directly by all implementations of [LocationStrategy]
1518
/// when

‎ngrouter/lib/src/route_definition.dart‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
/// @docImport 'directives/router_outlet_directive.dart';
2+
library;
3+
14
import 'dart:async';
25

36
import 'package:ngdart/angular.dart';
@@ -45,10 +48,10 @@ abstract class RouteDefinition {
4548

4649
/// Define a route from [path] that loads [component] into an outlet.
4750
///
48-
/// ```
51+
/// ```dart
4952
/// import 'contact_view.template.dart';
5053
///
51-
/// new RouteDefinition(
54+
/// RouteDefinition(
5255
/// path: 'contact',
5356
/// component: ContactViewComponentNgFactory,
5457
/// );
@@ -60,12 +63,12 @@ abstract class RouteDefinition {
6063
///
6164
/// Another way to create a RouteDefinition is by using a [RoutePath]. The
6265
/// routePath can also be used for other applications, such as creating URLs.
63-
/// ```
66+
/// ```dart
6467
/// RoutePath contactRoute = new RoutePath(
6568
/// path: 'contact',
6669
/// );
6770
///
68-
/// new RouteDefinition(
71+
/// RouteDefinition(
6972
/// routePath: contactRoute,
7073
/// component: ContactViewComponentNgFactory,
7174
/// );
@@ -81,7 +84,7 @@ abstract class RouteDefinition {
8184
/// Define a route from [path] that uses [loader] to resolve a component.
8285
///
8386
/// Can be used to prefetch/initialize, such as loading a deferred library:
84-
/// ```
87+
/// ```dart
8588
/// import 'contact_view.template.dart' deferred as contact_view;
8689
///
8790
/// Future<ComponentFactory> loadContentView() async {
@@ -92,8 +95,8 @@ abstract class RouteDefinition {
9295
///
9396
/// Then create a [RouteDefinition] that uses `loadContentView`:
9497
///
95-
/// ```
96-
/// new RouteDefinition.defer('contact', loadContactView);
98+
/// ```dart
99+
/// RouteDefinition.defer('contact', loadContactView);
97100
/// ```
98101
///
99102
/// An optional [prefetcher] can be specified to prefetch additional
@@ -118,9 +121,9 @@ abstract class RouteDefinition {
118121
RoutePath? routePath,
119122
}) = DeferredRouteDefinition._;
120123

121-
/// Configures a redirect from a [path] --> [to] another one.
124+
/// Configures a redirect from a [path] --> [redirectTo] another one.
122125
///
123-
/// ```
126+
/// ```dart
124127
/// new RouteDefinition.redirect(
125128
/// path: 'contact',
126129
/// redirectTo: 'about/contact',
@@ -136,10 +139,10 @@ abstract class RouteDefinition {
136139
/// both a default route, and redirect all unmatched routes, be sure to use
137140
/// '.+' as your path.
138141
///
139-
/// ```
142+
/// ```dart
140143
/// [
141-
/// new RouteDefinition(path: 'home', useAsDefault: true, ...),
142-
/// new RouteDefinition.redirect(path: '.+', redirectTo: 'home'),
144+
/// RouteDefinition(path: 'home', useAsDefault: true, ...),
145+
/// RouteDefinition.redirect(path: '.+', redirectTo: 'home'),
143146
/// ]
144147
/// ```
145148
factory RouteDefinition.redirect({

‎ngrouter/lib/src/route_path.dart‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ import 'url.dart';
88
/// endpoints of the application. Then, this path can be used to create
99
/// [RouteDefinition]s and generate URLs. This way, there are no circular
1010
/// dependencies.
11-
/// ```
12-
/// RoutePath contactRoute = new RoutePath(
11+
/// ```dart
12+
/// RoutePath contactRoute = RoutePath(
1313
/// path: 'contact',
1414
/// useAsDefault: true
1515
/// );
1616
///
17-
/// new RouteDefinition(
17+
/// RouteDefinition(
1818
/// routePath: contactRoute,
1919
/// component: MyComponentNgFactory,
2020
/// );

0 commit comments

Comments
 (0)