Есть ли способ избежать использования 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.

Ответы

Ответ 1

Ваш сотрудник не является строго правильным.

@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, если это тоже невозможно сделать (в этот момент вы, вероятно, делаете довольно забавное создание экземпляра, поэтому, вероятно, не смогли в любом случае, полагайтесь на автодокторское поколение).

Ответ 2

Возможно, я ошибаюсь, но из-за множества способов определения вещей в 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;