ember-cli-addon-docs-yuidoc

ember-cli-addon-docs-yuidoc

YUIDoc plugin for Ember CLI Addon Docs. This plugin adds automatic API documentation to your addon through a modified version of YUIDoc with support for:

• Modules
• Plain, non-class functions and constants
• Classes
  • Added support for accessors and fields
• Components (including arguments and yields)
• Helper functions
• Markdown in comments

Compatibility

• Ember.js v3.16 or above
• Ember CLI v2.13 or above
• Node.js v10 or above

Installation

ember install ember-cli-addon-docs-yuidoc

Usage

Documenting a Class

You can document classes using standard YUIDoc syntax with a few modifications

• You can use @field as an alias for @property
• You can use @accessor to reference a native getter/setter, or @computed for an Ember computed. These document the same, but @computed assumes a setter exists, whereas @accessor requires you to add the @set tag.
• You can add @static, @async, and @generator modifiers to methods

/**
  A foo class

  @class Foo
  @anArbitraryTag
  @public
*/
export default class Foo {
  /**
    A field named foo

    @field foo
    @type number
  */
  foo = 123;

  /**
    An accessor named baz

    @accessor baz
    @type any
    @set
  */
  get bar() {
    return this._baz;
  }

  set bar(val) {
    this._baz = val;
  }

  /**
    A static async method named grault

    @method grault
    @static
    @async
  */
  static async baz() {
    // ...
  }
}

Documenting Components

Components can be documented the same as classes, and will be automatically detected based on folder structure. They also have two extra types of properties:

• @yield which must be applied to the class itself
• @argument which is meant to represent an argument passed into the component

/**
  A foo-bar component. Usage:

  ```hbs
    {{#foo-bar baz=123 as |hash|}}

    {{/foo-bar}}
  ```

  @class FooBarComponent
  @yield {Hash} hash
  @yield {number} hash.foo
*/
export default Ember.Component.extend({
  /**
    @argument baz
    @type {number}
  */
  baz: -1
});

Documenting Modules

Modules will automatically be detected - no need to use @module. You can use the following tags:

• @function documents plain functions
• @variable, @const, or @constant documents variable values
• @export [named|default] specifies the export type
  • Classes are considered the default export unless specified otherwise, functions and variables are considered named unless specified otherwwise.

/**
  @class Foo
  @export named
*/
export class Foo {}

/**
  @function bar
  @export default
*/
export default function bar() {}

/**
  @const baz
  @type {number}
*/
export const baz = 123;

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.

Changelog

v1.1.0 (2024-02-22)

:rocket: Enhancement

• #235 Feature/add gts gjs support (@kdagnan)

:bug: Bug Fix

• #72 Closes #22 (@esbanarango)

Committers: 5

• Esteban (@esbanarango)
• Isaac Lee (@ijlee2)
• Kyle D. (@kdagnan)
• Robbie Wagner (@RobbieTheWagner)
• @dependabot-preview[bot]