Вопрос по jsdoc, code-documentation, google-closure-compiler, javascript – Как вернуть документ в JavaScript

13

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

Я пытаюсь следоватьJSDoc синтаксис, но, вероятно, продолжитGoogle Closure Compiler путь. Я могу использовать два тега @return и @returns в документации, просто для удобства переносимости (когда я настраиваю автогенерацию документации).

Теперь вопрос,how do you document the return of a custom anonymous object from a function? Например:

return {
    username: 'username',
    password: 'password',
    enabled:  true
};

В JsDoc есть пример того, как @param может быть задокументирован, чтобы ожидать объект с определенными полями, но не тег @returns. Точно так же документация Google Closure Compiler с типом записи является расплывчатой и не имеет примера для ее решения.

Тип возвратаObject, Почему бы вам просто не описать структуру объекта в несколько строк, как для параметра? jwueller
@elusive Да, я всегда могу это сделать, суть в том, чтобы позволить компилятору иметь информацию, с которой он может работать, а не только для чтения людьми. Azder
Увидетьdevelopers.google.com/closure/compiler/docs/… Rob W

Ваш Ответ

3   ответа
4

как показано ниже, с использованием возврата в качестве ключевого слова.https://github.com/senchalabs/jsduck/wiki/%40return

/**
 * @return {object} return An object with the following properties
 * @return {string} return.username Some username
 * @return {string} return.password Some password
 * @return {boolean} return.enabled Is the user enabled?
 */
function getObj () {
     return {
         username: 'username',
         password: 'password',
         enabled:  true
      };
}

Если вам нужно использовать его в нескольких местах, вам придется дублировать его или использовать@typedef, но я не понял, как добавлять комментарии к@typedef поэтому я использую что-то вроде следующего

/**
 * @typedef {username:string, password:string, enabled:boolean} MyType
 *  
 *  username: The name of the user 
 *  password: Some password
 *  enabled: Is the user enabled?
 */

/**
 * @return {MyType}
 */
function getObj () {
     return {
         username: 'username',
         password: 'password',
         enabled:  true
      };
}

Вы также можете попробовать предложение здесьКак я могу документировать тип в веб-шторме, используя только jsdoc?

1

function myFunction() {
    /**
     * Description of my function
     * @return {!Object.<string, string|boolean>} Returns an object containing username, password and enabled information
     */

    // Do stuff
    return {
        username: 'username',
        password: 'password',
        enabled:  true
    }
}
Или выше функции, если вы предпочитаете этот способ записи. (Я всегда помещаю их внутрь, поэтому, если я делаю .toString () для функции, я могу увидеть документацию)
ToString хороший. Спасибо Azder
13

JSDoc аннотации (и добавляет несколько своих). Увидетьссылка на аннотацию для компилятора для полной комплектации. Аннотация JSDoc аналогична аннотации JavaDoc и представляет собой блок комментариев, который начинается с/** (две звезды). Хотя каждая строка комментария часто начинается со своей собственной*это соглашение, которое не требуется. В каждой строке допускается только один тег JSDoc, но аргументы тега могут занимать несколько строк.

Аннотация обычно относится к следующему утверждению. Вот некоторые примеры:

Variable
/** @type {string} */ var a;
Type Cast
var b = /** @type {string} */ (window['foo']);

note the extra parenthesis

Named Function
/**
 * @param {string} bar
 * @return {boolean}
 */
function foo(bar) { return true; }
Function Expressions
/** @type {function(string):boolean} */
var foo = function(bar) { return true; }

var foo2 =
  /**
   * @param {string} bar
   * @return {boolean}
   */
  function(bar) { return true; }
Typedef

Сложные типы (включая объединения и типы записей) могут быть псевдонимами для удобства и удобства сопровождения с помощью typedef. Эти аннотации могут быть длинными, но могут быть разбиты на несколько строк для удобства чтения.

/** @typedef {{
 *             foo:string,
 *             bar:number,
 *             foobar:number|string
 *           }}
 */
var mytype;

Для вашего исходного примера есть несколько возможных способов аннотировать такую функцию, возвращаемое значение. Один из наиболее конкретных и удобных типов записей:

/** @return {{username:string, password:string, enabled:boolean}} */
function() {
  return {
    username: 'username',
    password: 'password',
    enabled:  true
  }
}

Обратите внимание на дополнительные{}, Также имейте в виду, что типы записей не будут препятствовать переименованию свойств.

Эта аннотация сообщает компилятору, что функция возвращает анонимный тип сusername, password а такжеenabled свойства. Другими допустимыми параметрами могут быть определение интерфейса в другом месте и приведение возвращаемого значения к этому интерфейсу. Наименее конкретная аннотация будетObject или же*.

Чтобы увидеть широкий спектр возможных аннотаций, взгляните навнешние файлы в проекте компилятора.

Я действительно прочитал это прежде, чем спросить, и использовал компилятор закрытия Google в прошлом. Я до сих пор не знаю, как поступить. Представьте себе необходимость документировать 20 полей в несколько строк. Нужно ли ставить звездочку (*) в начале каждой строки? В настоящее время проводятся дополнительные испытания. Azder
@ChadKillingsworth Привет, Чад, извини, что вторгся в старую ветку, но в Google это заняло много местаclosure annotations multi line, Я смотрю, как аннотировать сложные типы с помощью @typedef. Аннотация не может быть распределена по нескольким строкам (я думаю), но это сделает сложный typedef более читабельным. Например{{hands:number,walk:function(number):boolean,stop:function():boolean ... and lots more ...}}
Компилятор использует аннотации JSDoc. Я обновлю ответ, чтобы он был более полным.
Отдельные аннотации могут занимать более одной строки. Я добавил пример для typedefs.

Похожие вопросы