Документирование сложных объектов JavaScript с помощью пользовательской системы наследования

В настоящее время я пытаюсь перенести существующий API-интерфейс JavaScript на стороне сервера из существующей системы наследования с копированием и вставкой вручную в лучшую и более надежную систему. Чистое прототипирование нельзя использовать, потому что состояние (переменные) объектов также должно наследоваться и не должно переопределяться в родительских объектах.

Поэтому я думаю об использовании хорошего решения Джона Рейзига, описанного здесь: http://ejohn.org/blog/simple-javascript-inheritance/

которые отлично подходят для моего случая.

Единственная проблема, с которой я сталкиваюсь сейчас, заключается в том, что большинство фреймворков документации не будут обрабатывать объекты, построенные таким образом (ИЛИ я просто не знаю, как им сказать). Итак, мой вопрос: как я могу документировать такие классы:

namespace.ClassA = Class.extend({
    name : "",

    init: function(name){
        this.name = name;
    }
});

namespace.ClassB = ClassA.extend({
    sayName : function(){
        console.log(this.name);
    }
});

Я предпочитаю JsDoc, но я не мог придумать способ документировать такие классы с помощью JsDoc. Я также пробовал NaturalDocs, который вроде бы работал, но я действительно не хочу, чтобы весь этот дополнительный материал Python был в процессе сборки.

Я думаю, что основные проблемы, которые у меня есть, связаны с пространствами имен.

Например:

    /** @memberof namespace**/
    namespace.ClassB = ClassA.extend(
    /** @lends ClassB.prototype **/
    {
            /** @constructs **/
            init : function(){
            },

    sayName : function(){
        console.log(this.name);
    }
});

не будет включать или отображать ClassB в пространстве имен "пространство имен"


javascript jsdoc documentation ecmascript-5 jsdoc3
person Chris    schedule 07.03.2014    source источник
comment
Jsdoc может сделать несколько выводов для вас, если вы используете стиль, который он понимает. Если вы этого не сделаете, все равно можно явно указать jsdoc, что вы имеете в виду. Вам просто нужно быть более подробным в своей документации (используйте больше тегов @). Чтобы помочь нам дать ответ, который попадет в цель, было бы полезно, если бы вы могли показать нам, что вы пробовали и почему это вас не удовлетворяет. В противном случае очень легко дать ответ, который что-то даст, только для того, чтобы вы ответили, что это не то, что вы хотите, и т. д.   -  person Louis    schedule 07.03.2014

Ответы (1)


arrow_upward
1
arrow_downward

Посмотрите, работает ли следующее для вас. Обратите внимание, что ваш фрагмент кода сам по себе не является допустимым JavaScript, поскольку namespace нигде не определен. В любом случае jsdoc его обработает. Что мне нужно было сделать, так это быть более многословным, чем я мог бы быть в противном случае. Несколько заметок:

  1. Вы можете поместить доклет, определяющий ClassA, перед строкой, содержащей namespace.ClassA.

  2. Тег @lends требует полного пути: /** @lends namespace.ClassB.prototype */

Вот код:

/**
 * @namespace namespace
 */

namespace.ClassA = Class.extend({
    name : "",

    /**
     * @constructor
     * @memberof namespace
     * @name ClassA
     * @param name Blah.
     */
    init: function(name){
        this.name = name;
    }
});

/**
 * @constructor
 * @memberof namespace
 * @name ClassB
 */
namespace.ClassB = ClassA.extend(/** @lends namespace.ClassB.prototype */ {
    /**
     * @method
     */
    sayName : function(){
        console.log(this.name);
    }
});
person Louis    schedule 07.03.2014
comment
Действительно мило! Большое спасибо! - person Chris; 13.03.2014