Documentation Structure

CanJS’s documentation is broken down by pages for:

• library collections
• packages and modules and their exports
• functions, properties, and type definitions (typedefs) related to module exports

For example, can-observable-array/array.prototype.filter is a method that filters an array of ObservableArray:

import ObservableArray from "can-observable-array";

let users = new ObservableArray([{ name: "Justin" }, { name: "Matt" }]);

const filteredUsers = users.filter(function(item) {
  return item.name === "Justin";
}); //-> { name: "Justin: }

.filter is a function on the prototype of the ObservableArray export of the can-observable-array module. The can-observable-array is part of CanJS’s Core collection.

So understanding CanJS’s API pages are about understanding the relationships between:

• library collections
• packages and modules and their exports
• functions, properties, and type definitions (typedefs) related to module exports

…and what’s documented on those pages.

Library Collection pages

The API docs are divided in 4 collection pages:

• Core
• Ecosystem
• Infrastructure
• Legacy

Each collection page acts as an overview and cheat sheet for the modules and functionality contained within the collection.

The Core collection contains the documentation for the libraries that are use most commonly and directly within a CanJS application. This is where the custom element, observable, model, and routing libraries of CanJS are documented.

The Ecosystem collection contains less commonly used libraries or libraries that aren’t quite core ready yet. The most commonly used libraries here are can-fixture and can-stache-converters.

The Infrastructure collection contains the utility libraries that power the core and ecosystem collection. Often, this functionality is used indirectly. For example, the can-event-queue/map/map mixin is used to add on, off, and dispatch methods to can-observable-object and can-observable-array.

Sometimes Infrastructure is used directly. The most important examples are:

• can-queues is used to schedule tasks and batch changes for faster performance.
• can-dom-mutate/events/events provides special attributes, inserted, and removed events.
• can-view-callbacks lets you register behavior for custom elements and attributes.

Finally, the Legacy collection. This is for libraries that are no longer under active development. Hopefully, you aren’t there very often.

Look to library collection pages for a high level cheat and explanation of every module within the collection.

Package and Module Pages

A package or module documents the "direct" functionality of the export and provides an overview of all functionality contained within the module or package.

For example, can-observable-array documents the "direct" functionality of the export, namely the ObservableArray function that is exported. While classextendsObservableArray is the most common starting place when using ObservableArray, the ObservableArray export method can only be used like new ObservableArray() directly. This is why new ObservableArray() is documented on can-observable-array.

However, after the new ObservableArray() signature is detailed, can-observable-array has a #Use section that provides an overview of all functionality contained within the can-observable-array module.

Look to Package and module pages for details of what is specifically exported and an overview of what the module does, why it’s useful, and how to use it.

Functions, Properties, and Typedef pages

Within a module, there might be a variety of functions, properties and types a module might provide.

These values are generally organized by groupings. The most common groupings are:

• prototype - A property or function is on the prototype of a parent function.
• static - A property or method is a direct value on the parent function or object.
• events - Events dispatched on the parent object or instances of the parent function.
• types - Type definitions.

Let’s see a few examples and then give an overview of how their content is structured.

prototype

[can-observable-array.prototype.filter can-observable-array.prototype.filter] is in the prototype group on can-observable-array because filter is on the can-observable-array export’s prototype:

import ObservableArray from "can-observable-array";
ObservableArray.prototype.filter //-> function

Because of how JavaScript works, this means that you can call .filter directly on any instance of ObservableArray:

let hobbies = new ObservableArray(["learning", "programming"]);
hobbies.filter(hobby => hobby === "programming");

static

propertyDefaults in the static group on can-observable-object because propertyDefaults is a static property on the can-observable-object:

import ObservableObject from "can-observable-object";

class Person extends ObservableObject {
  static propertyDefaults = {}
}

types

Sometimes a method might expect data passed to it in a certain format, or returns data in another format. These formats are often described separate from the method.

For example, the can-fixture.store method returns an object of the Store type.

import fixture from 'can-fixture';

let todoStore = fixture.store([{id: 1, name: "trash"}]);

todoStore.createData  //-> function
todoStore.destroyData //-> function
todoStore.get         //-> function

As you can see above, a Store can have lots of methods itself: createData, destroyData, etc. So this type that isn’t directly accessible is documented under can-fixture’s types. It’s also specified as the return value of can-fixture.store.

Functions, Properties, and Typedef content

Each function, property, and typedef page will have one or more signature’s describing what is being documented.

Signatures are the what and the how. They should be precise on the behavior of what is being documented.

Some function, property, and typedef pages have #Use sections that give more information and examples on what is being documented.

Look to Functions, Properties, and Typedef pages to provide low-level details on a specific piece of CanJS’s API.

How to find what you’re looking for…

1. Get a good understand of the purpose behind each module.
2. Start with core modules.
3. Then check out infrastructure modules.

If you don’t find what you want on the lowest level, walk up to the parent module, it might be in its #Use section.

If not, let us know!