Skip to content

Commit e9c3889

Browse files
dgreenspdgreensp
committed
Document Blaze.Var, check in doctool.js
1 parent 310dcc5 commit e9c3889

File tree

6 files changed

+450
-11
lines changed

6 files changed

+450
-11
lines changed

‎packages/blaze/var.js

+102-6
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,87 @@
1-
// `[new] Blaze.Var(initializer[, equalsFunc])`
2-
//
3-
// A Var is a reactive mutable variable which may be initialized with a
4-
// value or a with a reactive function. If the initializer is a reactive
5-
// function, a Deps Computation is kicked off from the constructor
6-
// that updates the reactive variable.
1+
/**
2+
* ## [new] Blaze.Var(initializer[, equalsFunc])
3+
*
4+
* A reactive mutable variable which may be initialized with a value
5+
* or with a function to immediately autorun.
6+
*
7+
* * `initializer` - A function or a non-function value to use to
8+
* initialize the Var. If a function is given, it is called in
9+
* a `Deps.autorun` nested within the current Deps computation.
10+
*
11+
* * `equalsFunc` - A comparator function that takes two arguments
12+
* and returns a boolean. The value of the Var is only considered
13+
* to have changed (for the purpose of invalidating Computations)
14+
* if `equalsFunc(newValue, oldValue)` is truthy. If `equalsFunc`
15+
* is not given, `===` is used.
16+
*
17+
* Blaze.Var holds a single reactive value, providing `get` and `set`
18+
* methods that obey the usual reactive contract of a Deps data
19+
* source. (Namely, calling `get` causes the current Computation to
20+
* depend on the value, and calling `set` invalidates any dependent
21+
* Computations if it changes the value.)
22+
*
23+
* If a function is provided as an initializer, it is called to set
24+
* the initial value of the Var, and a Computation is started that
25+
* sets the value of the Var each time it re-runs. Because this new
26+
* (inner) Computation is nested in the current (outer) Computation,
27+
* when the outer Computation is invalidated, the inner Computation
28+
* is stopped. A Var whose Computation is stopped continues to be
29+
* reactively gettable and settable in the usual way.
30+
*
31+
* To avoid runaway Vars, an outer Computation is required to create a
32+
* Var with a function as initializer. As long as the outer Computation
33+
* is eventually invalidated or stopped, the Var will eventually
34+
* stop recomputing its value.
35+
*
36+
* Example:
37+
*
38+
* ```
39+
var a = Blaze.Var(1);
40+
var b = Blaze.Var(1);
41+
42+
Deps.autorun(function () {
43+
console.log('LOG:', a.get() + b.get());
44+
});
45+
// => LOG: 2
46+
47+
// These statements are assumed to be typed one at a time
48+
// at the console, giving the autorun a chance to re-run
49+
// between them.
50+
b.set(2); // => LOG: 3
51+
a.set(2); // => LOG: 4
52+
a.set(10), b.set(10); // => LOG: 20 (printed once)
53+
* ```
54+
*
55+
* To use a Var with an initializer function, an outer autorun is necessary
56+
* and is used to stop the recomputation.
57+
*
58+
* Example:
59+
*
60+
* ```
61+
var a = Blaze.Var(1);
62+
var b = Blaze.Var(1);
63+
64+
var handle = Deps.autorun(function () {
65+
var c = Blaze.Var(function () {
66+
return a.get() + b.get();
67+
});
68+
69+
Deps.autorun(function () {
70+
console.log('LOG:', c.get());
71+
});
72+
});
73+
// => LOG: 2
74+
75+
// These statements are assumed to be typed one at a time
76+
// at the console.
77+
b.set(2); // => LOG: 3
78+
a.set(2); // => LOG: 4
79+
a.set(10), b.set(10); // => LOG: 20 (printed once)
80+
handle.stop();
81+
a.set(1); // nothing printed
82+
* ```
83+
*/
84+
785
Blaze.Var = function (initializer, equalsFunc) {
886
var self = this;
987

@@ -35,12 +113,24 @@ Blaze.Var = function (initializer, equalsFunc) {
35113
};
36114

37115
_.extend(Blaze.Var.prototype, {
116+
/**
117+
* ## Blaze.Var#get()
118+
*
119+
* Returns the current value of the Var, causing the current
120+
* Deps Computation (if any) to depend on the value.
121+
*/
38122
get: function () {
39123
if (Deps.active)
40124
this.dep.depend();
41125

42126
return this.curValue;
43127
},
128+
/**
129+
* ## Blaze.Var#set(newValue)
130+
*
131+
* Sets the current value of the Var, causing any dependent
132+
* Computations to be invalidated.
133+
*/
44134
set: function (newValue) {
45135
var equals = this.equalsFunc;
46136
var oldValue = this.curValue;
@@ -55,6 +145,12 @@ _.extend(Blaze.Var.prototype, {
55145
this.curValue = newValue;
56146
this.dep.changed();
57147
},
148+
/**
149+
* ## Blaze.Var#toString()
150+
*
151+
* Returns a String representation of the Var, which
152+
* includes the string form of its value.
153+
*/
58154
toString: function () {
59155
return 'Var{' + this.get() + '}';
60156
}

‎packages/blaze/var.md

+102
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
*This file is automatically generated from [`var.js`](var.js).*
2+
3+
## [new] Blaze.Var(initializer[, equalsFunc])
4+
5+
A reactive mutable variable which may be initialized with a value
6+
or with a function to immediately autorun.
7+
8+
* `initializer` - A function or a non-function value to use to
9+
initialize the Var. If a function is given, it is called in
10+
a `Deps.autorun` nested within the current Deps computation.
11+
12+
* `equalsFunc` - A comparator function that takes two arguments
13+
and returns a boolean. The value of the Var is only considered
14+
to have changed (for the purpose of invalidating Computations)
15+
if `equalsFunc(newValue, oldValue)` is truthy. If `equalsFunc`
16+
is not given, `===` is used.
17+
18+
Blaze.Var holds a single reactive value, providing `get` and `set`
19+
methods that obey the usual reactive contract of a Deps data
20+
source. (Namely, calling `get` causes the current Computation to
21+
depend on the value, and calling `set` invalidates any dependent
22+
Computations if it changes the value.)
23+
24+
If a function is provided as an initializer, it is called to set
25+
the initial value of the Var, and a Computation is started that
26+
sets the value of the Var each time it re-runs. Because this new
27+
(inner) Computation is nested in the current (outer) Computation,
28+
when the outer Computation is invalidated, the inner Computation
29+
is stopped. A Var whose Computation is stopped continues to be
30+
reactively gettable and settable in the usual way.
31+
32+
To avoid runaway Vars, an outer Computation is required to create a
33+
Var with a function as initializer. As long as the outer Computation
34+
is eventually invalidated or stopped, the Var will eventually
35+
stop recomputing its value.
36+
37+
Example:
38+
39+
```
40+
var a = Blaze.Var(1);
41+
var b = Blaze.Var(1);
42+
43+
Deps.autorun(function () {
44+
console.log('LOG:', a.get() + b.get());
45+
});
46+
// => LOG: 2
47+
48+
// These statements are assumed to be typed one at a time
49+
// at the console, giving the autorun a chance to re-run
50+
// between them.
51+
b.set(2); // => LOG: 3
52+
a.set(2); // => LOG: 4
53+
a.set(10), b.set(10); // => LOG: 20 (printed once)
54+
```
55+
56+
To use a Var with an initializer function, an outer autorun is necessary
57+
and is used to stop the recomputation.
58+
59+
Example:
60+
61+
```
62+
var a = Blaze.Var(1);
63+
var b = Blaze.Var(1);
64+
65+
var handle = Deps.autorun(function () {
66+
var c = Blaze.Var(function () {
67+
return a.get() + b.get();
68+
});
69+
70+
Deps.autorun(function () {
71+
console.log('LOG:', c.get());
72+
});
73+
});
74+
// => LOG: 2
75+
76+
// These statements are assumed to be typed one at a time
77+
// at the console.
78+
b.set(2); // => LOG: 3
79+
a.set(2); // => LOG: 4
80+
a.set(10), b.set(10); // => LOG: 20 (printed once)
81+
handle.stop();
82+
a.set(1); // nothing printed
83+
```
84+
85+
86+
## Blaze.Var#get()
87+
88+
Returns the current value of the Var, causing the current
89+
Deps Computation (if any) to depend on the value.
90+
91+
92+
## Blaze.Var#set(newValue)
93+
94+
Sets the current value of the Var, causing any dependent
95+
Computations to be invalidated.
96+
97+
98+
## Blaze.Var#toString()
99+
100+
Returns a String representation of the Var, which
101+
includes the string form of its value.
102+

‎packages/htmljs/README.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,15 @@ templates during compilation.
1010
var UL = HTML.UL, LI = HTML.LI, B = HTML.B;
1111
1212
HTML.toHTML(
13-
UL({id: 'mylist'},
14-
LI({'class': 'item'}, "Hello ", B("world"), "!"),
15-
LI({'class': 'item'}, "Goodbye, world")))
13+
UL({id: 'mylist'},
14+
LI({'class': 'item'}, "Hello ", B("world"), "!"),
15+
LI({'class': 'item'}, "Goodbye, world")))
1616
```
1717

1818
```
1919
<ul id="mylist">
20-
<li class="item">Hello <b>world</b>!</li>
21-
<li class="item">Goodbye, world</li>
20+
<li class="item">Hello <b>world</b>!</li>
21+
<li class="item">Goodbye, world</li>
2222
</ul>
2323
```
2424

0 commit comments

Comments
 (0)