Можно ли указать jsdoc искать документацию по этому коду в отдельном от исходного кода файле?

Я хотел бы, чтобы встроенные комментарии были как можно короче, поскольку, по моему опыту, комментарии длиной более 3 или 4 строк имеют тенденцию замалчиваться, создавая много ненужных строк «прочитайте руководство».

По наследству я обязан придерживаться формата, совместимого с jsdoc, для документирования кода. Это требует, чтобы многие очевидные вещи были объявлены явно, если они должны быть правильно задокументированы. Практически каждый тег может попасть в эту категорию. Даже те, которые этого не делают, часто бесполезны для работающего разработчика.

Мое видение состоит в том, чтобы иметь краткую сводку внутри самого кода, которую разработчики действительно будут читать, но обращаться к отдельному файлу (или даже к дампу комментариев в том же файле, отдельно от того, где будут работать разработчики) для дополнительных тегов, например:

/**
 *  Used when making an example of the argument.
 *  @include someotherplace
 */
function example(argument) { stuff;}

...lots more code...

/**
 *  someotherplace
 *  @param argument The victim
 *  @since forever
 *  @other stuff
 */

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


javascript jsdoc documentation-generation
person user2999782    schedule 16.11.2013    source источник
comment
Какую версию jsdoc вы используете? Существуют значительные различия между jsdoc 2 и jsdoc 3.   -  person Louis    schedule 18.11.2013
comment
Я буду использовать ту версию, которая решит мою проблему, но 3 будет предпочтительнее на том основании, что она все еще активна.   -  person user2999782    schedule 19.11.2013
comment
Typescript позволяет хранить типы аргументов в отдельном файле. Может быть, это позволит вам задокументировать их и там.   -  person joeytwiddle    schedule 11.04.2016

Ответы (2)


arrow_upward
1
arrow_downward

С jsdoc3 я не думаю, что есть способ получить идеальное решение без необходимости писать новый плагин. (Я не знаю плагина, который уже делал бы это.)

Однако можно злоупотреблять тегами jsdoc, чтобы получить что-то не идеальное, но функциональное.

/**
 * @module foo
 */


/**
 * Used when making an example of the argument.
 * @see {module:foo.example_type}
 */
function example(argument) {
    //...
}

/**
 * someotherplace
 * @typedef {function} module:foo.example_type
 * @param argument The victim
 * @since forever
 */

Ключевым моментом является создание определения типа с уникальным именем, а затем использование @see для ссылки на это определение. @module и module: просто показывают, что это можно сделать с помощью модулей. Их можно просто зачищать для случаев, когда модули не нужны.

person Louis    schedule 23.11.2013

arrow_upward
0
arrow_downward

Как насчет тега {@link} и тегов tutorials {@tutorial}? Из документации:

{@tutorial} Учебники

Механизм учебных пособий позволяет включать не только краткую техническую документацию по API, связанную с кодом, но и более длинные, более поясняющие полностраничные учебные пособия.

Тег {@link} позволяет создать HTML-ссылку на другой задокументированный символ из текста описания любого тега.

Использование:

@anyTag This is some text {@link otherSymbol}.
person Anto Jurković    schedule 16.11.2013
comment
Спасибо, но это создает одну страницу для краткой документации со ссылкой на вторую страницу с дополнительной документацией. Я надеялся собрать их всех на одной странице. - person user2999782; 17.11.2013