Документирование плагинов

Remark и Rehype используют концепцию плагинов для расширения функциональности обработки Markdown и HTML. Плагины в этих библиотеках являются функциями, которые принимают один или несколько аргументов и возвращают функцию-посетитель, изменяющую или анализирующую дерево синтаксического разбора (AST). Это обеспечивает модульность и позволяет строить сложные цепочки обработки текста, применяя несколько плагинов последовательно.

Ключевые моменты архитектуры плагинов:

  • Функции-плагины принимают аргументы конфигурации.
  • Посетители (visitor functions) вызываются для каждого узла AST определённого типа.
  • Плагины могут быть синхронными или асинхронными.
  • Плагины Remark работают с Markdown AST (mdast), Rehype — с HTML AST (hast).

Структура документации плагина

Правильно оформленная документация плагина состоит из нескольких обязательных элементов:

  1. Название и версия — точное имя npm-пакета и поддерживаемая версия.
  2. Назначение — краткое описание функционала.
  3. Установка — команды для установки через npm или yarn.
  4. Использование — пример интеграции с unified().
  5. Конфигурация — список доступных опций и их возможные значения.
  6. API — детальное описание методов и событий.
  7. Примеры кода — демонстрация различных вариантов применения.
  8. Совместимость — версии Node.js и других библиотек.
  9. Дополнительно — советы по отладке, рекомендации по производительности.

Пример базовой структуры документации плагина:

## my-plugin

### Назначение
Добавляет уникальные идентификаторы для всех заголовков Markdown.

### Установка
```bash
npm install my-plugin

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

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkStringify from 'remark-stringify';
import myPlugin from 'my-plugin';

const processor = unified()
  .use(remarkParse)
  .use(myPlugin, { prefix: 'section-' })
  .use(remarkStringify);

const output = processor.processSync('# Заголовок').toString();
console.log(output);

Опции

Опция Тип По умолчанию Описание
prefix string ‘heading-’ Префикс для идентификаторов 

### Документирование опций

Каждая опция должна быть описана максимально подробно:

- **Тип**: указывайте точный тип данных (`string`, `number`, `boolean`, `array`, `function`).
- **Значение по умолчанию**: обязательно указывать, чтобы избежать недопонимания.
- **Описание поведения**: как изменение опции влияет на работу плагина.
- **Примеры использования**: несколько примеров, иллюстрирующих эффект изменения опции.

Пример для функции обратного вызова в конфигурации:

```js
{
  transform: (node) => {
    if (node.type === 'heading') {
      node.data = { ...node.data, custom: true };
    }
    return node;
  }
}

Обработка ошибок и валидация

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

  • Проверка типа аргументов.
  • Поведение при пустых или некорректных данных.
  • Встроенные сообщения об ошибках.
  • Возможность кастомной обработки ошибок через опции плагина.
if (typeof options.prefix !== 'string') {
  throw new TypeError('Опция prefix должна быть строкой');
}

Поддержка асинхронности

Плагины могут быть асинхронными, если требуется взаимодействие с внешними ресурсами или сложные вычисления:

async function asyncPlugin() {
  return async (tree) => {
    await someAsyncOperation();
    visit(tree, 'text', (node) => {
      node.value = node.value.toUpperCase();
    });
  };
}

Документация должна отражать, что обработка может быть асинхронной и показать, как правильно использовать await processor.process().

Примеры расширенного использования

В документации полезно показать цепочки плагинов с разными задачами: обработка ссылок, добавление метаданных, кастомные трансформации AST.

unified()
  .use(remarkParse)
  .use(remarkAutolinkHeadings)
  .use(myPlugin, { prefix: 'section-' })
  .use(remarkStringify);

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

Стандарты оформления

  • Markdown-форматирование для описания опций, примеров и таблиц.
  • Согласованная нотация типов данных.
  • Четкие комментарии к примерам кода.
  • Ясные указания на версии зависимостей.
  • Выделение ключевых моментов жирным шрифтом.

Автоматическая генерация документации

Интеграция с инструментами вроде TypeDoc, JSDoc или remark-docs позволяет автоматически создавать структурированную документацию на основе JSDoc-комментариев в коде. Рекомендуется включать:

  • Описание функций и параметров.
  • Типы возвращаемых значений.
  • Примеры использования внутри комментариев.
/**
 * Плагин добавляет идентификаторы заголовкам.
 * @param {Object} options - Настройки плагина
 * @param {string} options.prefix - Префикс идентификатора
 * @returns {Function} Посетитель AST
 */
function myPlugin(options = {}) {
  ...
}

Рекомендации по стилю и читаемости

  • Каждая опция — отдельная секция с таблицей или маркированным списком.
  • Примеры должны быть минимальными, но иллюстрировать реальную задачу.
  • Использовать единый стиль именования параметров и функций.
  • Включать указание на совместимость с версиями библиотеки и Node.js.
  • Дублировать ключевые моменты жирным шрифтом для быстрого восприятия.

Эта методика обеспечивает, что документация плагина Remark или Rehype будет понятной, структурированной и удобной для интеграции в проекты.

Оглавление