Skip to content

Commit

Permalink
Added docs for onEmit and offEmit Symbols (#27)
Browse files Browse the repository at this point in the history
* Added docs for onEmit and offEmit Symbols

* Removed not needed `apis.json` file

* Improved docs to include better example
  • Loading branch information
Mattchewone authored Nov 29, 2018
1 parent 155dac0 commit f0460f2
Show file tree
Hide file tree
Showing 3 changed files with 73 additions and 47 deletions.
47 changes: 0 additions & 47 deletions docs/apis.json

This file was deleted.

32 changes: 32 additions & 0 deletions docs/symbols-offEmit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
@typedef {function(function(*))} can-symbol/symbols/offEmit can.offEmit
@parent can-symbol/symbols/observe
@description Defines how observables can stop listening to the object's value being emitted.

@signature `@@can.offEmit( handler(newValue) )`

The `@@@@can.offEmit` symbol points to a function that unregisters
`handler` from being called when the object's value
is emitted.

```js
const obj = function(value) {
if(arguments.length >= 1) {
obj.currentValue = value;
obj.handlers.forEach(function(handler){
handler.call(obj, value);
});
} else {
return obj.currentValue;
}
};

obj[canSymbol.for("can.offEmit")] = function(handler){
if(!obj.handlers) {
obj.handlers = [];
}
obj.handlers.splice(obj.handlers.indexOf(handler), 1);
}
```

@this {*} any object with a mutable value
@param {function(this:*, *)} handler(newValue) The handler was previously added with [can-symbol/symbols/onEmit `@@can.onEmit`].
41 changes: 41 additions & 0 deletions docs/symbols-onEmit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
@typedef {function(function(*))} can-symbol/symbols/onEmit can.onEmit
@parent can-symbol/symbols/observe
@description Defines how observables can listen to the object's value whenever it is emitted.

@signature `@@can.onEmit( handler(newValue) )`

The `@@@@can.onEmit` symbol points to a function that registers
`handler` to be called back with the new value of the object when it
is emitted. `@@@@can.onEmit` can be used when you wish to emit a value that isn't changing.

```js
const obj = function(value) {
if(arguments.length >= 1) {
obj.currentValue = value;
obj.handlers.forEach(function(handler){
handler.call(obj, value);
});
} else {
return obj.currentValue;
}
};

obj[canSymbol.for("can.onEmit")] = function(handler){
if(!obj.handlers) {
obj.handlers = [];
}
obj.handlers.push(handler);
}

const listener = function (value) {
console.log('emitted', value);
}

obj[canSymbol.for("can.onEmit")](listener);

obj(5); // -> output: "emitted 5"
obj(5); // -> output: "emitted 5"
```

@this {*} any object with a mutable value
@param {function(this:*, *)} handler(newValue) The handler must be called back with `this` as the instance of the observable.

0 comments on commit f0460f2

Please sign in to comment.