Классы MooTools и JsDoc

Question

У меня есть следующий класс Moo:

Nem.Ui.Window = new Class({
    Implements: [Options, Events],

    options: {
        caption:    "Ventana",
        icon:       $empty,
        centered:   true,
        id:         $empty,
        width:      $empty,
        height:     $empty,
        modal:      false,
        desktop:    $empty,
        x:          $empty,
        y:          $empty,
        layout:     $empty
    },

    initialize: function(options)
    {
        this.setOptions(options);
        /* ... */
    },

    setHtmlContents: function(content)
    {
        /* ... */
    },

    setText: function(text)
    {
        /* ... */
    },

    close: function(win)
    {
        /* ... */
    },

    /* ... */
});

Я хочу задокументировать это с помощью JsDoc. Я читал, что вы можете использовать @lends [class].prototype внутри new Class и пометить initialize тегом @constructs. Как я могу пометить методы и события, такие?

I.E .: setHtmlContents должен быть методом, close должен быть событием.

Кроме того, элементы под options могут быть задокументированы, как-нибудь?

Answer 1

Вы можете пометить методы @function, а события - @event, но, поскольку функции по умолчанию правильно определяются, тег @function в вашем случае не будет необходим.

Элементы под options могут быть задокументированы с помощью @memberOf, в вашем примере с @memberOf Nem.Ui.Window#. Затем они будут показаны как options.optionName в сгенерированном JSDoc.

Полностью документированная версия вашего класса будет выглядеть примерно так:

/** @class This class represents a closabe UI window with changeable content. */
Nem.Ui.Window = new Class(
/** @lends Nem.Ui.Window# */
{
    Implements: [Options, Events],

    /** The options that can be set. */
    options: {
        /**
         * Some description for caption.
         * @memberOf Nem.Ui.Window#
         * @type String
         */
        caption:    "Ventana",
        /**
         * ...
         */
        icon:       $empty,
        centered:   true,
        id:         $empty,
        width:      $empty,
        height:     $empty,
        modal:      false,
        desktop:    $empty,
        x:          $empty,
        y:          $empty,
        layout:     $empty
    },

    /**
     * The constructor. Will be called automatically when a new instance of this class is created.
     *
     * @param {Object} options The options to set.
     */
    initialize: function(options)
    {
        this.setOptions(options);
        /* ... */
    },

    /**
     * Sets the HTML content of the window.
     *
     * @param {String} content The content to set.
     */
    setHtmlContents: function(content)
    {
        /* ... */
    },

    /**
     * Sets the inner text of the window.
     *
     * @param {String} text The text to set.
     */
    setText: function(text)
    {
        /* ... */
    },

    /**
     * Fired when the window is closed.
     *
     * @event
     * @param {Object} win The closed window.
     */
    close: function(win)
    {
        /* ... */
    },

    /* ... */

});

Я пропустил @constructs на initialize, так как тогда он вообще не будет отображаться в документе, и я пока не выяснил, как заставить это работать должным образом.

Для получения дополнительной информации о доступных тегах и их функциях см. TagReference в wiki jsdoc-toolkit.

Answer 2

Я наконец решил эту проблему с помощью Natural Docs.