Spec-Zone.ru › JSDoc

Настройка JSDoc с помощью конфигурационного файла

Содержание

  • Форматы конфигурационных файлов
  • Значения по умолчанию для конфигурации
  • Настройка плагинов
  • Указание глубины рекурсии
  • Указание входных файлов
  • Указание типа источника
  • Включение параметров командной строки в конфигурационный файл
  • Настройка тегов и словарей тегов
  • Настройка шаблонов
  • Ссылки

Форматы конфигурационных файлов

Чтобы настроить поведение JSDoc, вы можете предоставить конфигурационный файл в одном из следующих форматов:

  • Файл в формате JSON. В JSDoc 3.3.0 и более поздних версиях этот файл может содержать комментарии.
  • Модуль CommonJS, экспортирующий единственный объект конфигурации. Этот формат поддерживается в JSDoc

3.5.0 и более поздних версиях.

Чтобы запустить JSDoc с конфигурационным файлом, используйте параметр командной строки -c (например, jsdoc -c /path/to/conf.json или jsdoc -c /path/to/conf.js).

В следующих примерах показан простой конфигурационный файл, который включает плагин Markdown JSDoc. Параметры конфигурации JSDoc подробно описаны в следующих разделах.

Файл конфигурации JSON
{
    "plugins": ["plugins/markdown"]
}
Файл конфигурации JavaScript
'use strict';

module.exports = {
    plugins: ['plugins/markdown']
};

Для более подробного примера файла конфигурации JSON см. файл conf.json.EXAMPLE.

Значения по умолчанию для конфигурации

Если вы не указываете конфигурационный файл, JSDoc использует следующие параметры конфигурации:

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

Это означает:

  • Плагины не загружаются (plugins).
  • Если рекурсия включена с помощью флага командной строки -r, JSDoc будет искать файлы на глубину 10 уровней (recurseDepth).
  • Обрабатываются только файлы, заканчивающиеся на .js, .jsdoc, и .jsx (source.includePattern).
  • Любой файл, начинающийся с символа подчеркивания, или находящийся в директории, начинающейся с символа подчеркивания, будет проигнорирован (source.excludePattern).
  • JSDoc поддерживает код, использующий модули ES2015 (sourceType).
  • JSDoc позволяет использовать нераспознанные теги (tags.allowUnknownTags).
  • Включены как стандартные теги JSDoc, так и теги Closure Compiler (tags.dictionaries).
  • Встроенные {@link} теги отображаются в обычном тексте (templates.cleverLinks, templates.monospaceLinks).

Эти и другие параметры описаны в следующих разделах.

Настройка плагинов

Чтобы включить плагины, добавьте их пути (относительно папки JSDoc) в массив plugins.

Например, следующий файл конфигурации JSON включит плагин Markdown, который преобразует текст в формате Markdown в HTML, и плагин "summarize", который автоматически генерирует резюме для каждого документа:

Файл конфигурации JSON с плагинами
{
    "plugins": [
        "plugins/markdown",
        "plugins/summarize"
    ]
}

Дополнительную информацию см. в справочнике по плагинам, а папку с плагинами JSDoc см. в plugins папке.

Вы можете настроить плагин Markdown, добавив объект markdown в ваш конфигурационный файл. Подробности см. в разделе Настройка плагина Markdown.

Указание глубины рекурсии

Параметр recurseDepth управляет тем, на сколько уровней вглубь JSDoc будет рекурсивно искать файлы исходного кода и учебные пособия. Этот параметр доступен в JSDoc 3.5.0 и более поздних версиях. Этот параметр используется только если вы также указали флаг командной строки -r, который указывает JSDoc на рекурсивный поиск входных файлов.

{
    "recurseDepth": 10
}

Указание входных файлов

Набор параметров source, в сочетании с путями, указанными для JSDoc в командной строке, определяет набор входных файлов, которые JSDoc использует для генерации документации.

{
    "source": {
        "include": [ /* array of paths to files to generate documentation for */ ],
        "exclude": [ /* array of paths to exclude */ ],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}
  • source.include: необязательный массив путей, содержащих файлы, для которых JSDoc должен сгенерировать документацию. Указанные в командной строке пути комбинируются с этими путями. Вы можете использовать опцию командной строки -r для рекурсивного поиска в поддиректориях.
  • source.exclude: необязательный массив путей, которые JSDoc должен проигнорировать. В JSDoc 3.3.0 и более поздних версиях этот массив может включать поддиректории путей в source.include.
  • source.includePattern: необязательная строка, интерпретируемая как регулярное выражение. Если она присутствует, все имена файлов должны соответствовать этому регулярному выражению, чтобы быть обработаны JSDoc. По умолчанию этот параметр установлен на ".+\.js(doc|x)?$", что означает, что будут обработаны только файлы с расширениями .js, .jsdoc, и .jsx.
  • source.excludePattern: необязательная строка, интерпретируемая как регулярное выражение. Если она присутствует, все файлы, соответствующие этому регулярному выражению, будут проигнорированы. По умолчанию этот параметр настроен так, что файлы, начинающиеся с символа подчеркивания (или находящиеся в директориях, начинающихся с символа подчеркивания), игнорируются.

Эти параметры интерпретируются в следующем порядке:

  1. Начните со всех путей, указанных в командной строке и в source.include.
  2. Для каждого найденного в шаге 1 файла, если присутствует регулярное выражение source.includePattern, имя файла должно соответствовать ему, в противном случае он игнорируется.
  3. Для каждого файла, оставшегося после шага 2, если присутствует регулярное выражение source.excludePattern, все имена файлов, соответствующие этому регулярному выражению, игнорируются.
  4. Для каждого файла, оставшегося после шага 3, если путь к файлу содержится в source.exclude, он игнорируется.

Все оставшиеся файлы после этих четырех шагов обрабатываются JSDoc.

В качестве примера, предположим, что у вас есть следующая структура файлов:

myProject/
|- a.js
|- b.js
|- c.js
|- _private
|  |- a.js
|- lib/
   |- a.js
   |- ignore.js
   |- d.txt

Кроме того, предположим, что ваш файл conf.json выглядит так:

{
    "source": {
        "include": ["myProject/a.js", "myProject/lib", "myProject/_private"],
        "exclude": ["myProject/lib/ignore.js"],
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    }
}

Если вы запустите jsdoc myProject/c.js -c /path/to/my/conf.json -r из файла, содержащего папку myProject, JSDoc сгенерирует документацию для следующих файлов:

  • myProject/a.js
  • myProject/c.js
  • myProject/lib/a.js

Вот почему:

  1. Исходя из source.include и путей, указанных в командной строке, JSDoc начинает с этих файлов:
    • myProject/c.js (из командной строки)
    • myProject/a.js (из source.include)
    • myProject/lib/a.js, myProject/lib/ignore.js, myProject/lib/d.txt (из source.include и используя опцию -r)
    • myProject/_private/a.js (из source.include)
  2. JSDoc применяет source.includePattern, оставляя нас со всеми вышеперечисленными файлами, *кроме* myProject/lib/d.txt, который не заканчивается на .js, .jsdoc, или .jsx.
  3. JSDoc применяет source.excludePattern, что удаляет myProject/_private/a.js.
  4. JSDoc применяет source.exclude, что удаляет myProject/lib/ignore.js.

Указание типа источника

Параметр sourceType влияет на то, как JSDoc анализирует ваши файлы JavaScript. Этот параметр доступен в JSDoc 3.5.0 и более поздних версиях. Этот параметр принимает следующие значения:

  • module (по умолчанию): используйте это значение для большинства типов файлов JavaScript.
  • script: используйте это значение, если JSDoc выводит ошибки, такие как Delete of an unqualified identifier in strict mode при анализе вашего кода.
{
    "sourceType": "module"
}

Включение параметров командной строки в конфигурационный файл

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

Файл конфигурации JSON с параметрами командной строки
{
    "opts": {
        "template": "templates/default",  // same as -t templates/default
        "encoding": "utf8",               // same as -e utf8
        "destination": "./out/",          // same as -d ./out/
        "recurse": true,                  // same as -r
        "tutorials": "path/to/tutorials", // same as -u path/to/tutorials
    }
}

Используя параметры source.include и opts, вы можете поместить почти все аргументы JSDoc в конфигурационный файл, так что командная строка сводится к:

jsdoc -c /path/to/conf.json

Если параметры указаны как в командной строке, так и в конфигурационном файле, приоритет отдается командной строке.

Настройка тегов и словарей тегов

Параметры в tags управляют тем, какие теги JSDoc разрешены и как интерпретируется каждый тег.

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    }
}

Свойство tags.allowUnknownTags влияет на то, как JSDoc обрабатывает нераспознанные теги. Если вы установите этот параметр в false, и JSDoc найдёт тег, который он не распознаёт (например, @foo), JSDoc выведет предупреждение. По умолчанию этот параметр установлен на true. В JSDoc 3.4.1 и более поздних версиях вы также можете установить это свойство в массив имён тегов, которые JSDoc должен разрешить (например, ["foo","bar"]).

Свойство tags.dictionaries управляет тегами, которые JSDoc распознаёт, а также тем, как JSDoc интерпретирует теги, которые он распознаёт. В JSDoc 3.3.0 и более поздних версиях есть два встроенных словаря тегов:

  • jsdoc: основные теги JSDoc.
  • closure: теги Closure Compiler.

По умолчанию оба словаря включены. Кроме того, по умолчанию словарь jsdoc находится в списке первым; в результате, если словарь jsdoc обрабатывает тег по-другому, чем словарь closure, версия тега из jsdoc имеет приоритет.

Если вы используете JSDoc с проектом Closure Compiler и хотите избежать использования тегов, не распознаваемых Closure Compiler, измените параметр tags.dictionaries на ["closure"]. Вы также можете установить это значение в ["closure","jsdoc"], если вы хотите разрешить основные теги JSDoc, но убедиться, что теги, специфичные для Closure Compiler, интерпретируются так, как они интерпретируются Closure Compiler.

Настройка шаблонов

Параметры в templates влияют на внешний вид и содержимое сгенерированной документации. Плагины от сторонних разработчиков могут не реализовывать все эти параметры. См. Настройка стандартного шаблона JSDoc для дополнительных параметров, поддерживаемых стандартным шаблоном.

{
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

Если templates.monospaceLinks имеет значение true, весь текст ссылок из встроенного тега {@link} будет отображаться в моноширинном шрифте.

END_OF_DOCUMENT_MARKER

Если templates.cleverLinks истинно, {@link asdf} будет отображаться обычным шрифтом, если asdf является URL, и моноширинным шрифтом в противном случае. Например, {@link http://github.com} будет отображаться простым текстом, но {@link MyNamespace.myFunction} — моноширинным.

Если templates.cleverLinks истинно, templates.monospaceLinks игнорируется.

Связанные ссылки

  • Аргументы командной строки для JSDoc
  • О плагинах JSDoc
  • Использование плагина Markdown

© 2011–2017 the contributors to the JSDoc 3 documentation project
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://jsdoc.app/about-configuring-jsdoc.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API