JsDocのミクシン

mixinタグ

• @mixin [<MixinName>]

A mixin provides functionality that is intended to be added to other objects. If desired, you can use the @mixin tag to indicate that an object is a mixin. You can then add the @mixes tag to objects that use the mixin.

---

ミクシンは、他のオブジェクトに追加することを意図した機能性を提供するオブジェクトです。もしお望みなら、@mixin タグを使って、オブジェクトがミクシンであることを明示できます。そして、@mixes タグにより、そのミクシンを使用する側のオブジェクトを示します。

/**
 * This provides methods used for event handling. It's not meant to
 * be used directly.
 *
 * @mixin
 */
var Eventful = {
    /**
     * Register a handler function to be called whenever this event is fired.
     * @param {string} eventName - Name of the event.
     * @param {function(Object)} handler - The handler to call.
     */
    on: function(eventName, handler) {
        // code...
    },

    /**
     * Fire an event, causing all handlers for that event name to run.
     * @param {string} eventName - Name of the event.
     * @param {Object} eventData - The data provided to each handler.
     */
    fire: function(eventName, eventData) {
        // code...
    }
};

mixesタグ

• @mixes <OtherObjectPath>

The @mixes tag indicates that the current object mixes in all the members from OtherObjectPath, which is a @mixin.

---

@mixesタグは、当該のオブジェクトが、ミクシンである他のオブジェクト OtherObjectPath からすべてのメンバーをミックス導入することを示します。

/**
 * @constructor FormButton
 * @mixes Eventful
 */
var FormButton = function() {
    // code...
};
FormButton.prototype.press = function() {
  this.fire('press', {});
}
mix(Eventful).into(FormButton.prototype);

説明

ミクシンは継承のひとつの実現形態とも考えられる。

• 継承元がミクシン、@mixin で明示する。
• 継承先がミクシンの利用者、@mixes ミクシン で明示する。

ミクシン継承を利用するモノは、クラスインスタンスつうよりアクティブオブジェクト（関数が生えたオブジェクト）。ミクシンの利用者側に、ミクシンのプロパティ（の値または参照）がすべてコピーされる。

ミクシンとミクシン利用者は対等ではないが、機能は混ぜ合わされる。ミックスは動的に行われるので、上書き〈オーバーライド〉も発生する。

ミクシンのミックスは、オブジェクトを実際に変更して機能性を追加するが、オブジェクトからの参照先に機能性を保たせる場合はデリゲーションになる。デリゲーション先を、個人的にはヘルパーと呼んでいる。

残念ながら、JsDocタグに @helper, @delegates のようなものはない。