Есть ли способ избежать использования аннотации JSDoc @method

Лично я не большой поклонник сгенерированной документации (я больше люблю "читать исходный код Люка"), но я вижу, как такая документация может быть полезна другим. Обычно их создание документации не влияет на меня, за исключением одного: @method.

Большинство аннотаций JSDoc (например, @param) по-прежнему очень полезны для тех, кто читает исходный код, но @method на 100% избыточен:

/*
 * @param num number to add five to
 * @method addFive
 */
function addFive(num) { ...

Так что мне бы очень хотелось избежать того, чтобы сотни @method строк загромождали наш код. Однако мой коллега считает, что @method необходимо для генераторов JSDoc (он использует YUI), чтобы они могли генерировать списки методов классов.

Итак, мой вопрос (к экспертам JSDoc): есть ли способ создать полезную документацию (т.е. с помощью перечисленных методов класса) без @method? Или, если @method действительно требуется, существует ли какой-нибудь генератор JSDoc, который может вывести имя метода из имени функции, чтобы я мог уйти с @method вместо @method addFive?

P.S. Если есть ответ типа «вы делаете это неправильно», который не дает прямого ответа на вопрос, но предлагает способ полностью избежать проблемы, я бы хотел его услышать; Я, конечно, не эксперт по JSDoc.


javascript jsdoc
person machineghost    schedule 26.07.2012    source источник

Ответы (2)


arrow_upward
14
arrow_downward

Ваш коллега не совсем прав.

@method - это расширение JSDoc3, которое является синонимом @function, т. Е. определено здесь.

Как указано в этих документах, вам нужно только @function, чтобы заставить JSDoc распознать переменную как функцию. Примером этого может быть:

/**
 * @function
 */
var func = functionGenerator.generate();

С объектной точки зрения вы хотели бы делать то же самое всякий раз, когда вы назначаете объект Function члену объекта неочевидным способом (под «неочевидным» я имею в виду с точки зрения статического анализа, т. Е. Если вы без использования выражения функции).

Итак, что-то вроде

var ageGetter = function() {
    console.log("A lady never tells");
}

var Person = {

  name: "Gertrude", 

  getAge: ageGetter

  getName: function() {
    return this.name;
  }
}

Потребует явного использования @method или @function для getAge, но не для getName.

Заключительный момент: вам не нужно явно указывать @method имя, если это тоже невозможно сделать (в этот момент вы, вероятно, делаете довольно забавный экземпляр, поэтому, вероятно, не могли полагаться на auto doc- поколения все равно много).

person Dancrumb    schedule 03.08.2012

arrow_upward
3
arrow_downward

Я могу ошибаться здесь, но из-за множества способов определения вещей в JavaScript вам как бы нужны @method для определенных определений.

// JSDoc will recognize this as an object member
var obj = {
    mymethod: function() {}
};

// There is no way for JSDoc to tell where my method is going to end up
var mymethod = function() {};
obj.mymethod = mymethod;
person Torsten Walter    schedule 28.07.2012