Skip to content

Commit

Permalink
Cleanup markdown sample code (#39)
Browse files Browse the repository at this point in the history
* fix markdown code snippets

* Use const/let in sample code

* run eslint on markdown code

* run eslint on markdown code
  • Loading branch information
Christopher Baker committed Feb 15, 2018
1 parent f916944 commit e864f0e
Show file tree
Hide file tree
Showing 8 changed files with 92 additions and 91 deletions.
13 changes: 7 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,12 +78,13 @@ To output minified versions, in the `build.js` add `minify: true` to the outputs

```js
{
// in build.js export config
outputs: {
"+cjs": { minify: true },
"+amd": { minify: true },
"+global-js": { minify: true }
}

// in build.js export config
outputs: {
"+cjs": { minify: true },
"+amd": { minify: true },
"+global-js": { minify: true }
}
}
```

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ CanJS Debugger
With StealJS, you can import this module directly in a template that is autorendered:

```js
import plugin from 'can-debug';
import plugin from "can-debug";
```

### CommonJS use
Expand All @@ -20,7 +20,7 @@ Use `require` to load `can-debug` and everything else
needed to create a template that uses `can-debug`:

```js
var plugin = require("can-debug");
import plugin from "can-debug";
```

### Standalone use
Expand Down
98 changes: 49 additions & 49 deletions doc/can-debug.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ affect each other, specifically CanJS's observables and DOM nodes.

Exports an object with the following methods:

```js
```
{
drawGraph // Draws the dependency graph in a new window
logWhatIChange // Log what the observable affects
Expand All @@ -24,33 +24,33 @@ Exports an object with the following methods:

## Use

`can-debug` exports functions to log how observables affect each other. These
`can-debug` exports functions to log how observables affect each other. These
functions can be used to understand the flow of data throughout an application.

The following example shows how to use the [can-debug.logWhatChangesMe] function
The following example shows how to use the [can-debug.logWhatChangesMe] function
to log what affects the value of the `fullName` property on the `me` Person instance.

```js
var Person = DefineMap.extend("Person", {
first: "string",
last: "string",
fullName: {
get: function() {
return this.first + " " + this.last;
}
}
});

var me = new Person({ first: "John", last: "Doe" });
debug.logWhatChangesMe(me, "fullName");
const Person = DefineMap.extend( "Person", {
first: "string",
last: "string",
fullName: {
get: function() {
return this.first + " " + this.last;
}
}
} );

const me = new Person( { first: "John", last: "Doe" } );
debug.logWhatChangesMe( me, "fullName" );
```

Which prints out the following message to the browser's console:

<img class="bit-docs-screenshot" alt="logWhatchangesMe full output" src="../node_modules/can-debug/doc/what-changes-me-full.png">

At first, the message might be very confusing, specially so in larger examples
where multiple observables are involved. Let's break it up in smaller sections to
At first, the message might be very confusing, specially so in larger examples
where multiple observables are involved. Let's break it up in smaller sections to
get a better understanding of what each means:

<img class="bit-docs-screenshot" alt="logWhatchangesMe output" src="../node_modules/can-debug/doc/what-changes-me-top.png">
Expand All @@ -62,23 +62,23 @@ The following values are printed out for each observable in the dependency graph
- And finally the **observable's dependencies** in the green border box.

Each observable will be contained in a console group, this group is labeled
using a human-readable name that describes what the the observable does (blue
border box), in most cases this name is made out of the constructor name decorated
using a human-readable name that describes what the the observable does (blue
border box), in most cases this name is made out of the constructor name decorated
with some metadata and it's returned by [can-reflect.getName].

The box with the green border lists the dependencies of the observable in the
blue border box, these dependencies are grouped based on their relation to the
parent observable, in its current version `can-debug` outputs the following
The box with the green border lists the dependencies of the observable in the
blue border box, these dependencies are grouped based on their relation to the
parent observable, in its current version `can-debug` outputs the following
groups:

- **DERIVED FROM**: observables used internally by the parent to derive its value.
- **MUTATED BY**: observables that set the value of the parent observable
- **MUTATED BY**: observables that set the value of the parent observable
these are mostly found inside CanJS internals, where observables interact with
each other, like [can-stache-bindings].
- **TWO WAY**: observables that are both derived and mutation dependencies.

The observables in each group are printed out recursively using the same format we
just described, We can can confirm this by expanding `Person{}.fullName`'s dependencies
The observables in each group are printed out recursively using the same format we
just described, We can can confirm this by expanding `Person{}.fullName`'s dependencies
group:

<img class="bit-docs-screenshot" alt="dependencies" src="../node_modules/can-debug/doc/what-changes-me-deps.png">
Expand All @@ -88,58 +88,58 @@ The whole output can be read as:
`Person{}.fullName` derives its value from `Observation<Person{}'s fullName getter>`,
which in turn derive its value from `Person{}.first` and `Person{}.last` values.

> Note: Please keep in mind that some of the observables printed out in the console
> do not necessarily match the ones found in user's application code, as mentioned
> before, observables used internally are listed as dependencies, such is the case
> Note: Please keep in mind that some of the observables printed out in the console
> do not necessarily match the ones found in user's application code, as mentioned
> before, observables used internally are listed as dependencies, such is the case
> of `Observation<Person{}'s fullName getter>` in the example.
The following demos a live version of the previous example, click the `logWhatChangesMe`
button and open the browser's console tab to inspect the generated message:

@demo demos/can-debug/log-what-changes-map.html

Understanding the relationships between types is helpful to debug certain kind
of issues, but most of the time you want to understand what affects another kind
Understanding the relationships between types is helpful to debug certain kind
of issues, but most of the time you want to understand what affects another kind
of observables: DOM nodes.

The following example builds upon the previous code, and adds two `<input>` elements
that are cross bound to the `first` and `last` properties of the `Person` map, then
`fullName` is printed out in the page using a `<h1>` element.

Then [can-debug.logWhatChangesMe] is called to log what observables affect the
Then [can-debug.logWhatChangesMe] is called to log what observables affect the
`<h1>` element:

```js
var Person = DefineMap.extend("Person", {
const Person = DefineMap.extend( "Person", {
first: "string",
last: "string",
fullName: {
get() {
return `${this.first} ${this.last}`;
}
}
});
} );

var template = stache(`
<h1 id="full">{{fullName}}</h1>
<input id="first" value:bind="first">
<input id="last" value:bind="last">
`);
const template = stache( `
<h1 id="full">{{fullName}}</h1>
<input id="first" value:bind="first">
<input id="last" value:bind="last">
` );

var scope = new Person({ first: "Jane", last: "Doe" });
document.body.appendChild(template(scope));
const scope = new Person( { first: "Jane", last: "Doe" } );
document.body.appendChild( template( scope ) );

debug.logWhatChangeMe(document.querySelect("#full"));
debug.logWhatChangeMe( document.querySelect( "#full" ) );
```

This prints out the following message:

<img class="bit-docs-screenshot" alt="logWhatChangesMe" src="../node_modules/can-debug/doc/what-changes-me-input.png">

That's a long message! but once you have identified the output pattern, making sense
of it is a lot easier. The observables highlighted in blue border boxes are the most
important to get a high level overview of the dependency graph, while the observables
in between help you make sense of how data flows from the top `<h1>` element down to
That's a long message! but once you have identified the output pattern, making sense
of it is a lot easier. The observables highlighted in blue border boxes are the most
important to get a high level overview of the dependency graph, while the observables
in between help you make sense of how data flows from the top `<h1>` element down to
each `<input>` element and back up to the `<h1>` heading element.

The following demos a live version of the previous example, click the `logWhatChangesMe`
Expand All @@ -150,14 +150,14 @@ button and open the browser's console tab to inspect the generated message:
## How to write can-debug friendly code

CanJS's internal observables are decorated with metadata and symbols used by
`can-debug` to build the dependency graph.
`can-debug` to build the dependency graph.

For most CanJS applications, the default instrumentation should be enough to get
reliable logs from `can-debug`; but custom observable types require some extra
For most CanJS applications, the default instrumentation should be enough to get
reliable logs from `can-debug`; but custom observable types require some extra
work to make them easier to debug.

The whole process can be sumarized in the following steps:

- Give the observable a human-readable name, check out [can-reflect.getName] docs.
- Register how the observable interacts with other observables, check out
- Register how the observable interacts with other observables, check out
[can-reflect-dependencies] docs.
10 changes: 5 additions & 5 deletions doc/draw-graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,20 @@ to display (in a new browser window) the dependency graph of the `fullName` prop
of the `me` Person instance:

```js
var debug = require("can-debug");
import debug from "can-debug";

var Person = DefineMap.extend("Person", {
const Person = DefineMap.extend( "Person", {
first: "string",
last: "string",
fullName: {
get() {
return `${this.first} ${this.last}`;
}
}
});
} );

var me = new Person({ first: "John", last: "Doe" });
debug.drawGraph(me, "fullName");
const me = new Person( { first: "John", last: "Doe" } );
debug.drawGraph( me, "fullName" );
```

Calling `debug.drawGraph` opens up a new browser window like this:
Expand Down
10 changes: 5 additions & 5 deletions doc/get-debug-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,21 @@ That means it's possible to get only the observables used to derive the value fr
or to get all the observables that are changed by a given object.

```js
var Person = DefineMap.extend("Person", {
const Person = DefineMap.extend( "Person", {
first: "string",
last: "string",
fullName: {
get: function() {
return this.first + " " + this.last;
}
}
});
} );

var me = new Person({ first: "John", last: "Doe" });
me.on("fullName", function() {});
const me = new Person( { first: "John", last: "Doe" } );
me.on( "fullName", function() {} );

console.log(
debug.getDebugData(debug.getGraph(me, "fullName")),
debug.getDebugData( debug.getGraph( me, "fullName" ) ),
"whatChangesMe"
);
```
Expand Down
10 changes: 5 additions & 5 deletions doc/get-graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,20 @@ as "x" changes "y"; if the arrow goes in the opposite direction it can be read a
is changed by "y" or "x" derives its value from "y".

```js
var Person = DefineMap.extend("Person", {
const Person = DefineMap.extend( "Person", {
first: "string",
last: "string",
fullName: {
get: function() {
return this.first + " " + this.last;
}
}
});
} );

var me = new Person({ first: "John", last: "Doe" });
me.on("fullName", function() {});
const me = new Person( { first: "John", last: "Doe" } );
me.on( "fullName", function() {} );

var graph = debug.getGraph(me, "fullName");
const graph = debug.getGraph( me, "fullName" );
```

Using a visualization library, the graph returned in the above example looks like
Expand Down
10 changes: 5 additions & 5 deletions doc/log-what-changes-me.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,20 @@ property that derives its value from `first` and `last`. Then it calls `logWhatC
to log what affects the `fullName` property of the `me` Person instance:

```js
var debug = require("can-debug");
import debug from "can-debug";

var Person = DefineMap.extend("Person", {
const Person = DefineMap.extend( "Person", {
first: "string",
last: "string",
fullName: {
get() {
return `${this.first} ${this.last}`;
}
}
});
} );

var me = new Person({ first: "John", last: "Doe" });
debug.logWhatChangesMe(me, "fullName");
const me = new Person( { first: "John", last: "Doe" } );
debug.logWhatChangesMe( me, "fullName" );
```

Calling `logWhatChangesMe` prints out the following message to the browser's
Expand Down
28 changes: 14 additions & 14 deletions doc/log-what-i-change.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,31 +17,31 @@ and prints out the `fullName` value in a `<h1>` element. Then it calls `logWhatI
passing the `<input>` element reference with id "first".

```js
var debug = require("can-debug");
var stache = require("can-stache");
var DefineMap = require("can-define/map/map");
require("can-stache-bindings");
import debug from "can-debug";
import stache from "can-stache";
import DefineMap from "can-define/map/map";
require( "can-stache-bindings" );

var Person = DefineMap.extend("Person", {
const Person = DefineMap.extend( "Person", {
first: "string",
last: "string",
fullName: {
get() {
return `${this.first} ${this.last}`;
}
}
});
} );

var view = stache(`
<h1 id="full">{{fullName}}</h1>
<input id="first" value:bind="first">
<input id="last" value:bind="last">
`);
const view = stache( `
<h1 id="full">{{fullName}}</h1>
<input id="first" value:bind="first">
<input id="last" value:bind="last">
` );

var scope = new Person({ first: "Jane", last: "Doe" });
document.body.appendChild(view(scope));
const scope = new Person( { first: "Jane", last: "Doe" } );
document.body.appendChild( view( scope ) );

debug.logWhatIChange(document.querySelector("#first"), "value");
debug.logWhatIChange( document.querySelector( "#first" ), "value" );
```

It logs the observables affected by the `value` attribute of the `<input>`
Expand Down

0 comments on commit e864f0e

Please sign in to comment.