Skip to content

Commit 4028f0d

Browse files
ykmnkmiykmnkmi
committed
ngforms: update comments.
1 parent b44ca84 commit 4028f0d

16 files changed

+178
-151
lines changed

‎ngforms/lib/ngforms.dart‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
///
66
/// This module is not included in the `angular` module; you must import the
77
/// forms module explicitly.
8+
///
9+
/// @docImport 'src/model.dart';
810
library; // name the library so we can run dartdoc on it by name.
911

1012
import 'src/directives/radio_control_value_accessor.dart'
@@ -62,7 +64,10 @@ export 'src/validators.dart' show ngValidators, Validators;
6264
/// ### Example
6365
///
6466
/// ```dart
65-
/// runApp(MyAppNgFactory, [formProviders]);
67+
/// @GenerateInjector(formProviders)
68+
/// final InjectorFactory injector = ng.injector$Injector;
69+
///
70+
/// runApp(MyAppNgFactory, createInjector: injector);
6671
/// ````
6772
const List<Type> formProviders = [RadioControlRegistry];
6873

‎ngforms/lib/src/directives/default_value_accessor.dart‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,9 @@ const defaultValueAccessor = ExistingProvider.forToken(
1818
/// [NgModel], [NgFormControl], and [NgControlName] directives.
1919
///
2020
/// ### Example
21-
/// <input type="text" ngControl="searchQuery">
21+
/// ```html
22+
/// <input type="text" ngControl="searchQuery">
23+
/// ```
2224
@Directive(
2325
selector: 'input:not([type=checkbox])[ngControl],'
2426
'textarea[ngControl],'

‎ngforms/lib/src/directives/form_interface.dart‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/// @docImport 'ng_form.dart';
2+
/// @docImport 'ng_form_model.dart';
3+
library;
4+
15
import '../model.dart' show Control, AbstractControlGroup;
26
import 'ng_control.dart' show NgControl;
37
import 'ng_control_group.dart' show NgControlGroup;

‎ngforms/lib/src/directives/ng_control_group.dart‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/// @docImport 'ng_form.dart';
2+
/// @docImport 'ng_form_model.dart';
3+
library;
4+
15
import 'dart:async';
26

37
import 'package:ngdart/angular.dart';
@@ -23,29 +27,29 @@ import 'validators.dart' show ValidatorFn;
2327
/// <div>
2428
/// <h2>Angular Control &amp; AbstractControlGroup Example</h2>
2529
/// <form #f="ngForm">
26-
/// <div ngControlGroup="name" #cg-name="form">
30+
/// <div ngControlGroup="name" #name="ngForm">
2731
/// <h3>Enter your name:</h3>
2832
/// <p>First: <input ngControl="first" required></p>
2933
/// <p>Middle: <input ngControl="middle"></p>
3034
/// <p>Last: <input ngControl="last" required></p>
3135
/// </div>
3236
/// <h3>Name value:</h3>
33-
/// <pre>{{valueOf(cgName)}}</pre>
34-
/// <p>Name is {{cgName?.control?.valid ? "valid" : "invalid"}}</p>
37+
/// <pre>{{valueOf(name)}}</pre>
38+
/// <p>Name is {{name.control!.valid ? "valid" : "invalid"}}</p>
3539
/// <h3>What's your favorite food?</h3>
3640
/// <p><input ngControl="food"></p>
3741
/// <h3>Form value</h3>
3842
/// <pre>{{valueOf(f)}}</pre>
3943
/// </form>
4044
/// </div>
41-
/// '''
42-
/// })
45+
/// ''',
46+
/// )
4347
/// class App {
44-
/// String valueOf(NgControlGroup cg) {
45-
/// if (cg.control == null) {
48+
/// String? valueOf(ControlContainer cc) {
49+
/// if (cc.control == null) {
4650
/// return null;
4751
/// }
48-
/// return json.encode(cg.control.value, null, 2);
52+
/// return json.encode(cc.control!.value);
4953
/// }
5054
/// }
5155
/// ```

‎ngforms/lib/src/directives/ng_control_name.dart‎

Lines changed: 34 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/// @docImport 'ng_form.dart';
2+
/// @docImport 'ng_form_model.dart';
3+
library;
4+
15
import 'dart:async';
26

37
import 'package:ngdart/angular.dart';
@@ -22,20 +26,21 @@ import 'shared.dart' show controlPath;
2226
///
2327
/// ```dart
2428
/// @Component(
25-
/// selector: "login-comp",
26-
/// directives: const [formDirectives],
27-
/// template: '''
28-
/// <form #f="ngForm" (submit)='onLogIn(f.value)'>
29-
/// Login <input type='text' ngControl='login' #l="form">
30-
/// <div *ngIf="!l.valid">Login is invalid</div>
29+
/// selector: 'login-comp',
30+
/// directives: const [coreDirectives, formDirectives],
31+
/// template: '''
32+
/// <form #f="ngForm" (submit)="onLogIn(f.value)">
33+
/// Login <input type="text" ngControl="login" #l="ngForm">
34+
/// <div *ngIf="!l.valid!">Login is invalid</div>
3135
///
32-
/// Password <input type='password' ngControl='password'>
33-
/// <button type='submit'>Log in!</button>
34-
/// </form>
35-
/// ''')
36+
/// Password <input type="password" ngControl="password">
37+
/// <button type="submit">Log in!</button>
38+
/// </form>
39+
/// ''',
40+
/// )
3641
/// class LoginComp {
37-
/// void onLogIn(value) {
38-
/// // value === {'login': 'some login', 'password': 'some password'}
42+
/// void onLogIn(dynamic value) {
43+
/// // value == {'login': 'some login', 'password': 'some password'}
3944
/// }
4045
/// }
4146
/// ```
@@ -44,23 +49,25 @@ import 'shared.dart' show controlPath;
4449
///
4550
/// ```dart
4651
/// @Component(
47-
/// selector: "login-comp",
48-
/// directives: [formDirectives],
49-
/// template: '''
50-
/// <form (submit)='onLogIn()'>
51-
/// Login <input type='text' ngControl='login' [(ngModel)]="credentials.login">
52-
/// Password <input type='password' ngControl='password'
53-
/// [(ngModel)]="credentials.password">
54-
/// <button type='submit'>Log in!</button>
55-
/// </form>
56-
/// ''')
52+
/// selector: 'login-comp',
53+
/// directives: const [formDirectives],
54+
/// template: '''
55+
/// <form (submit)="onLogIn()">
56+
/// Login <input type="text" ngControl="login" [(ngModel)]="login">
57+
/// Password <input type="password" ngControl="password"
58+
/// [(ngModel)]="password">
59+
/// <button type="submit">Log in!</button>
60+
/// </form>
61+
/// ''')
5762
/// class LoginComp {
58-
/// credentials: {login:string, password:string};
63+
/// String? login;
5964
///
60-
/// onLogIn(): void {
61-
/// // credentials.login === "some login"
62-
/// // credentials.password === "some password"
63-
/// }
65+
/// String? password;
66+
///
67+
/// void onLogIn() {
68+
/// // login == 'some login'
69+
/// // password == some password'
70+
/// }
6471
/// }
6572
/// ```
6673
@Directive(

‎ngforms/lib/src/directives/ng_form.dart‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ import 'shared.dart' show setUpControl, setUpControlGroup, composeValidators;
1717
///
1818
/// ### Typical Use
1919
///
20-
/// Include `formDirectives` in the `directives` section of a [View] annotation
21-
/// to use `NgForm` and its associated controls.
20+
/// Include `formDirectives` in the `directives` section of a component
21+
/// annotation to use `NgForm` and its associated controls.
2222
///
2323
/// ### Structure
2424
///
@@ -36,6 +36,7 @@ import 'shared.dart' show setUpControl, setUpControlGroup, composeValidators;
3636
/// ```dart
3737
/// @Component(
3838
/// selector: 'my-app',
39+
/// directives: const [coreDirectives, formDirectives],
3940
/// template: '''
4041
/// <div>
4142
/// <p>Submit the form to see the data object Angular builds</p>
@@ -55,15 +56,14 @@ import 'shared.dart' show setUpControl, setUpControlGroup, composeValidators;
5556
/// <p>Form data submitted:</p>
5657
/// </form>
5758
/// <pre>{{data}}</pre>
58-
/// </div>''',
59-
/// directives: const [coreDirectives, formDirectives]
60-
/// })
59+
/// </div>
60+
/// ''',
61+
/// )
6162
/// class App {
62-
///
63-
/// String data;
63+
/// String? data;
6464
///
6565
/// void onSubmit(data) {
66-
/// data = JSON.encode(data);
66+
/// this.data = json.encode(data);
6767
/// }
6868
/// }
6969
/// ```

‎ngforms/lib/src/directives/ng_form_control.dart‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import 'shared.dart' show setUpControl;
1919
/// ```dart
2020
/// @Component(
2121
/// selector: 'my-app',
22+
/// directives: const [coreDirectives, formDirectives]
2223
/// template: '''
2324
/// <div>
2425
/// <h2>NgFormControl Example</h2>
@@ -30,10 +31,9 @@ import 'shared.dart' show setUpControl;
3031
/// </form>
3132
/// </div>
3233
/// ''',
33-
/// directives: const [coreDirectives, formDirectives]
3434
/// )
3535
/// class App {
36-
/// Control loginControl = new Control('');
36+
/// Control loginControl = Control('');
3737
/// }
3838
/// ```
3939
///
@@ -45,13 +45,15 @@ import 'shared.dart' show setUpControl;
4545
///
4646
/// ```dart
4747
/// @Component(
48-
/// selector: "login-comp",
49-
/// directives: const [formDirectives],
50-
/// template: "<input type='text' [ngFormControl]='loginControl' [(ngModel)]='login'>"
51-
/// )
48+
/// selector: 'login-comp',
49+
/// directives: const [formDirectives],
50+
/// template: '''
51+
/// <input type="text" [ngFormControl]="loginControl" [(ngModel)]="login">
52+
/// ''',
53+
/// )
5254
/// class LoginComp {
53-
/// Control loginControl = new Control('');
54-
/// String login;
55+
/// Control loginControl = new Control('');
56+
/// String? login;
5557
/// }
5658
/// ```
5759
@Directive(

‎ngforms/lib/src/directives/ng_form_model.dart‎

Lines changed: 30 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -19,31 +19,27 @@ import 'validators.dart' show ValidatorFn;
1919
/// ```dart
2020
/// @Component(
2121
/// selector: 'my-app',
22+
/// directives: const [formDirectives],
2223
/// template: '''
2324
/// <div>
2425
/// <h2>NgFormModel Example</h2>
25-
/// <form [ngFormModel]='loginForm">
26+
/// <form [ngFormModel]="loginForm">
2627
/// <p>Login: <input type="text" ngControl="login"></p>
2728
/// <p>Password: <input type="password" ngControl="password"></p>
2829
/// </form>
2930
/// <p>Value:</p>
3031
/// <pre>{{value}}</pre>
3132
/// </div>
3233
/// ''',
33-
/// directives: const [formDirectives]
34-
/// })
34+
/// )
3535
/// class App {
36-
/// ControlGroup loginForm;
37-
///
38-
/// App() {
39-
/// loginForm = new ControlGroup({
40-
/// login: new Control(""),
41-
/// password: new Control("")
42-
/// });
43-
/// }
36+
/// ControlGroup loginForm = ControlGroup({
37+
/// 'login': Control(''),
38+
/// 'password': Control(''),
39+
/// });
4440
///
4541
/// String get value {
46-
/// return JSON.encode(loginForm.value);
42+
/// return json.encode(loginForm.value);
4743
/// }
4844
/// }
4945
/// ```
@@ -52,31 +48,30 @@ import 'validators.dart' show ValidatorFn;
5248
///
5349
/// ```dart
5450
/// @Component(
55-
/// selector: "login-comp",
56-
/// directives: const [formDirectives],
57-
/// template: '''
58-
/// <form [ngFormModel]='loginForm'>
59-
/// Login <input type='text' ngControl='login' [(ngModel)]='credentials.login'>
60-
/// Password <input type='password' ngControl='password'
61-
/// [(ngModel)]='credentials.password'>
62-
/// <button (click)="onLogin()">Login</button>
63-
/// </form>'''
64-
/// )
65-
/// class LoginComp {
66-
/// credentials: {login: string, password: string};
67-
/// ControlGroup loginForm;
51+
/// selector: 'login-comp',
52+
/// directives: const [formDirectives],
53+
/// template: '''
54+
/// <form [ngFormModel]="loginForm">
55+
/// Login <input type="text" ngControl="login" [(ngModel)]="login">
56+
/// Password <input type="password" ngControl="password"
57+
/// [(ngModel)]="password">
58+
/// <button (click)="onLogin()">Login</button>
59+
/// </form>
60+
/// ''',
61+
/// )
62+
/// class HelloWorldComponent {
63+
/// String? login;
64+
/// String? password;
6865
///
69-
/// LoginComp() {
70-
/// loginForm = new ControlGroup({
71-
/// login: new Control(""),
72-
/// password: new Control("")
73-
/// });
74-
/// }
66+
/// ControlGroup loginForm = ControlGroup({
67+
/// 'login': Control(''),
68+
/// 'password': Control(''),
69+
/// });
7570
///
76-
/// void onLogin() {
77-
/// // credentials.login === 'some login'
78-
/// // credentials.password === 'some password'
79-
/// }
71+
/// void onLogin() {
72+
/// // login == 'some login'
73+
/// // password == 'some password'
74+
/// }
8075
/// }
8176
/// ```
8277
@Directive(

‎ngforms/lib/src/directives/ng_model.dart‎

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

36
import 'package:meta/dart2js.dart' as dart2js;

‎ngforms/lib/src/directives/number_value_accessor.dart‎

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

38
import 'package:ngdart/angular.dart';
@@ -13,9 +18,10 @@ const numberValueAccessor = ExistingProvider.forToken(
1318
/// The accessor for writing a number value and listening to changes that is used by the
1419
/// [NgModel], [NgFormControl], and [NgControlName] directives.
1520
///
16-
/// ### Example
17-
///
18-
/// <input type="number" [(ngModel)]="age">
21+
/// ### Example
22+
/// ```html
23+
/// <input type="number" [(ngModel)]="age">
24+
/// ```
1925
@Directive(
2026
selector: 'input[type=number][ngControl],'
2127
'input[type=number][ngFormControl],'

0 commit comments

Comments
 (0)