ember-documentary

The default blueprint for ember-cli addons.

Usage no npm install needed!

<script type="module">
  import emberDocumentary from 'https://cdn.skypack.dev/ember-documentary';
</script>

README

Ember-documentary Build Status

Add JSDocs to your Ember components, then access those JSDocs elsewhere through an Ember component provided by ember-documentary. Great for living style guides.

Note: This addon is a work in progress, so the API may change a lot. To that end, this addon won't follow semver for versions 0.0.x. Once this addon hits version 0.1.0, this addon will follow semver from then on.

Installation

  • git clone this repository
  • npm install
  • bower install

Usage

Add JSDocs to your Ember components like so:

/**
 * Provides JSDoc information about a particular component.
 *
 * Pass a block to this component to define your own template and operate upon
 * the JSDoc information. The block should take one argument, which is the
 * instance of this component. So, you can use this component like so:
 *
 * ```hbs
 * {{#documentary-component 'documentary-component' as |meta|}}
 *   {{meta.signature}}
 * {{/documentary-component}}
 * ```
 *
 * @param {String} componentPath - Path to the component.
 */
export default Ember.Component.extend({
});

Then in an Ember template, you can access the JSDoc information. An example:

{{#documentary-component 'documentary-component' as |meta|}}
  {{meta.signature}}
{{/documentary-component}}

meta is an instance of documentary-component, so you should be able to access every property in the component definition. Still, a rudimentary list of the API is below.

API

  • signature: a generated signature for the Ember component. Example: {{cool-component title requiredParam=String [optionalParam="default"]}}
  • description: The main body of the JSDoc comment, without any tag information.
  • params: Array. (Keyword) param information for the Ember component.
  • positionalParams: Array. Positional param information for the Ember component.
  • ast: The raw JSDoc AST if you want to do low-level operations.

All the JSDoc tags (lines that start with @, like @param) have great documentation over at usejsdoc.

New JSDoc tag: @positionalParam

@positionalParam is not part of the official JSDoc spec. It is a custom tag I made for this library. It's implemented by preprocessing JSDoc comments and replacing any form of:

@positionalParam {OptionalType} name

with:

@param {OptionalType} __positional_param__name

The prefix __positional_param__ is stripped from the param name inside the documentary-component Ember.Component.

Tests

  • npm test (Runs ember try:testall to test your addon against multiple Ember versions)
  • ember test
  • ember test --server

License

Copyright Kickstarter, PBC.

Released under an MIT License.