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