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

Содержание

• Обзор
• Включение плагина Markdown
• Преобразование Markdown в дополнительных тегах JSDoc
• Исключение стандартных тегов из обработки Markdown
• Жесткое переносы текста на разрывах строк
• Добавление атрибутов ID к заголовкам

Обзор

JSDoc включает плагин Markdown, который автоматически преобразует текст в формате Markdown в HTML. Вы можете использовать этот плагин с любой JSDoc-шаблоном. В JSDoc 3.2.2 и более поздних версиях плагин Markdown использует парсер Markdown marked.

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

По умолчанию JSDoc ищет текст в формате Markdown в следующих тегах JSDoc:

• @author
• @classdesc
• @description (включая описания без тегов в начале комментария JSDoc)
• @param
• @property
• @returns
• @see
• @throws

Включение плагина Markdown

Чтобы включить плагин Markdown, добавьте строку plugins/markdown в массив plugins в вашем файле конфигурации JSDoc:

{
    "plugins": ["plugins/markdown"]
}

Преобразование Markdown в дополнительных тегах JSDoc

По умолчанию плагин Markdown обрабатывает только определенные теги JSDoc для текста Markdown. Вы можете обрабатывать текст Markdown в других тегах, добавив свойство markdown.tags в файл конфигурации JSDoc. Свойство markdown.tags содержит массив дополнительных свойств doclet, которые могут содержать текст Markdown. (В большинстве случаев имя свойства doclet совпадает с именем тега. Однако некоторые теги хранятся по-другому; например, тег @param хранится в свойстве params doclet. Если вы не уверены, как текст тега хранится в doclet, запустите JSDoc с тегом -X/--explain, который выведет каждый doclet в консоль.)

Например, если теги foo и bar принимают значения, которые хранятся в свойствах doclet foo и bar, вы можете включить обработку Markdown для этих тегов, добавив следующие настройки в файл конфигурации JSDoc:

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "tags": ["foo", "bar"]
    }
}

Исключение стандартных тегов из обработки Markdown

Чтобы предотвратить обработку плагином Markdown любых стандартных тегов JSDoc, добавьте свойство markdown.excludeTags в файл конфигурации JSDoc. Свойство markdown.excludeTags содержит массив стандартных тегов, которые не должны обрабатываться для текста Markdown.

Например, чтобы исключить тег author из обработки Markdown:

{
    "plugins": ["plugins/markdown"],
    "markdown": {
        "excludeTags": ["author"]
    }
}

Жесткое переносы текста на разрывах строк

По умолчанию плагин Markdown не выполняет жесткий перенос текста на разрывах строк. Это связано с тем, что комментарий JSDoc обычно занимает несколько строк. Если вы предпочитаете жесткий перенос текста на разрывах строк, установите свойство markdown.hardwrap файла конфигурации JSDoc в true. Это свойство доступно в JSDoc 3.4.0 и более поздних версиях.

Добавление атрибутов ID к заголовкам

По умолчанию плагин Markdown не добавляет атрибут id к каждому заголовку HTML. Чтобы автоматически добавлять атрибуты id на основе текста заголовка, установите свойство markdown.idInHeadings файла конфигурации JSDoc в true. Это свойство доступно в JSDoc 3.4.0 и более поздних версиях.