Формат блока функции в API-референсах — расследование и рекомендация
Статус: решение зафиксировано в docs-template.md (раздел «Документирование функции», 2026-09-10) — этот файл теперь архив расследования и обоснование, а не открытый вопрос.
Ретрофит color-value-tools — завершён (2026-09-10). Пилот на cache.md, после подтверждения раскатан на остальные 6 файлов гайда (обе локали) — parsing.md, conversions.md, formatting.md, manipulation.md, color-generation.md, accessibility.md. Сборка чистая, ноль оставшихся bullet-блоков.
Архитектурный вопрос по «5 composables на одной странице» — решён (2026-09-10), см. «Решение», пункт 3 ниже, и docs-template.md («Несколько тонких composables/hooks без группировки на одной странице»).
Полный сайт-аудит — завершён (2026-09-10). Та же пара проблем (сырой ##, и местами отменённый bullet-формат блока) найдена и исправлена ещё в 9 пакетах (обе локали каждого файла) — таблица ниже, «Полный список файлов на исправление», отражает финальное состояние. Итоговая проверка: npm run build чистая; grep по всему packages/ на **Takes:**/**Принимает:** и на сырые H2-сигнатуры (включая generic-параметры вида useResponsive<T>(), getState<T>(), которые первый проход регулярки пропустил) — оба дают 0 совпадений. По ходу починки заголовков нашлись и были исправлены 2 повисшие перекрёстные ссылки на старые (сырые) якоря: os-detect/api-reference.md → vue.md#useprimaryinput/react.md#useprimaryinput (новый якорь — #primary-input / #основнои-способ-ввода, обратите внимание на й→и в RU-слаге) и vue-error-boundary-kit/router.md → nuxt.md#usenuxterrorboundary (новый якорь — #app-wide-error-boundary / #граница-ошибок-на-все-приложение, ё→е в RU-слаге). npm run build не ловит такие битые якоря сам — проверяет только существование страницы, не конкретного id на ней — поэтому такие ссылки нужно было искать grep'ом отдельно после переименования заголовков.
Зачем
За время работы над os-detect всплыло, что в разных пакетах один и тот же тип контента — «функция без затей: сигнатура, что принимает, что возвращает, как ведёт себя» — оформлен по-разному. Не единичный случай: ниже — фактическая инвентаризация по всем 18 пакетам, не предположение.
Что фактически используется у нас прямо сейчас
Три разных паттерна, все — в активных, недавно тронутых файлах:
1. Полный, с настоящими заголовками (### Parameters / ### Return value или #### Returns)
Самый массовый паттерн — уже используется в 10+ пакетах для Composables/Components/hooks-архетипа (своя страница на сущность): inview (все composable-страницы), vue-image-kit, vue-i18n-kit, vue-worker-kit, vue-storage-kit, vue-virtual-scroller-kit, vue-error-boundary-kit, vue-form-schema, vue-state-machine, vue-toast-kit, часть vue-command-palette.
Это ровно то, что уже описано в docs-template.md («Документирование composable») — трогать не нужно, он и так доминирующий и совпадает с тем, что делают крупные проекты (см. ниже).
2. Компактный, с bullet-списком - **Takes:** / - **Returns:**
Используется в color-value-tools — во всех 7 файлах гайда (parsing.md, cache.md, conversions.md, formatting.md, manipulation.md, color-generation.md, accessibility.md), и было в os-detect/{vue,react}.md (composable/hook-страницы, где эта разметка вообще была не на своём месте — там нужен паттерн №1).
3. Компактный, без каких-либо меток — голая строка с типом + проза
Используется в responsive-media/utilities.md (и частично в rest-pipeline-js, vue-command-palette, css-magic-gradient), теперь и в os-detect/api-reference.md — это тот вариант, который выбрали для os-detect в этой сессии.
Пример (responsive-media/utilities.md):
## `getMediaQueries()`
`Record<string, string>`
Возвращает сгенерированные строки CSS media query для каждого ключа брейкпоинта.Что делают крупные проекты (живое расследование, не по памяти)
Проверил напрямую пять источников — три с открытым кодом близкого нам формата (утилиты + Vue/React composables/hooks), плюс эталон индустрии (MDN) и официальный референс Vue.
MDN (IntersectionObserver constructor)
Классический эталон технического референса. Реальные заголовки: Syntax → Parameters → Return value → Exceptions → Examples. Параметры — как definition list (термин = имя параметра, описание — вложенным текстом), вложенные под-параметры (например, поля callback-объекта) — тем же паттерном на уровень глубже.
react.dev (useState)
#### Parameters {/*parameters*/}
- `initialState`: The value you want the state to be initially. …
#### Returns {/*returns*/}
`useState` returns an array with exactly two values:
1. The current state. …
2. The `set` function …Parameters/Returns — настоящие заголовки (####), не bullet-метки внутри абзаца. Каждый параметр — bullet с именем в бэктиках и описанием после двоеточия. Есть ещё отдельный #### Caveats для нюансов поведения — у нас за это отвечает проза после блока кода.
vuejs.org (computed())
computed()
-----------
Takes a getter function and returns a readonly reactive ref …
- **Type**
```ts
function computed<T>(getter: ...): Readonly<Ref<Readonly<T>>>
```
- **Example**
…
- **See also**
…Отдельного Parameters/Returns нет вообще — вся сигнатура (включая типы параметров) живёт в одном TS-блоке под меткой Type, а нюансы — прозой в первом абзаце и в Details (когда он есть). Bullet здесь — не «Takes/Returns», а название РАЗДЕЛА (Type/Example/See also), с поддержкой markdown списка просто как способ визуально сгруппировать.
vueuse.org (isDefined, useMouse)
Самый радикальный вариант: никакого прозаического Parameters/Returns вообще — сигнатура (полный TS-интерфейс с JSDoc-комментариями на каждое поле) сама и есть документация, в свёрнутом блоке «Type Declarations». Работает у них, потому что генерируется из исходников автоматически (TypeDoc/аналог) — нам не подходит один в один, у нас весь гайд пишется руками, а не выкачивается из TSDoc-комментариев.
zod.dev
Формальных Parameters/Returns нет вовсе — чистая проза + примеры кода один за другим. Подходит для API, где почти все методы принимают один интуитивно понятный аргумент; для функций с 3-5 параметрами (как у многих наших composables) читателю пришлось бы восстанавливать список параметров из примеров кода — не подходит нам как основной формат.
Вывод из исследования
Ни один крупный проект не использует ровно тот компактный bullet-паттерн - **Takes:** / - **Returns:**, что прижился в color-value-tools. Ближайший реальный аналог — react.dev, но там Parameters/Returns — полноценные заголовки с bullet-list ВНУТРИ раздела, а не двухстрочная сводка вместо заголовка.
Зато вариант №3 (голая строка типа + проза), который уже выбрали для os-detect, — прямое, чуть более компактное прочтение паттерна vuejs.org Type: строка с типом = заменяет **Type**-блок для случаев, когда сигнатура умещается в одну строку и не нужен отдельный ts блок только под тип.
Рекомендация
Не один универсальный формат на всё — у нас реально два разных по форме вида контента, и MDN/react.dev/vuejs.org сами через это разграничение проходят (Reference-страница на хук vs страница-раздел на группу методов):
А. Своя страница на сущность (composable/hook/component/directive/class-метод) — оставить как есть, паттерн №1 уже задокументирован в docs-template.md и совпадает с react.dev/MDN. Ничего не менять.
Б. Несколько мелких функций на одной странице (Functions-архетип, ### functionName() на уровень глубже) — закрепить паттерн №3 (os-detect/api-reference.md, responsive-media/utilities.md) как единственный:
### `functionName(param?)`
`ReturnType` (опустить строку целиком, если возврат `void` и
самоочевиден из названия — как `destroy()` в responsive-media)
Проза: что делает, поведение в разных окружениях, кэшируется или нет,
edge-кейсы — всё сюда, никаких bullet-списков `Takes:/Returns:/Node.js:`.
\`\`\`ts
...
\`\`\`
### `param` (только если у функции реально есть параметры)
`Type` · default: `value`
Описание параметра.Паттерн №2 (bullet Takes:/Returns:) — вывести из обращения полностью, он не встречается ни в одном проверенном стороннем источнике и не даёт ничего, чего не даёт №3 короче.
Что перевести на выбранный формат, если паттерн Б утверждается
Единственный пакет, который целиком написан в паттерне №2 и требует полного ретрофита — color-value-tools, 7 файлов × 2 локали:
parsing.md,cache.md,conversions.md,formatting.md,manipulation.md,color-generation.md,accessibility.md
Это самый функционально насыщенный пакет в реестре (упоминался в памяти как крупный аудит с несколькими найденными багами) — ретрофит только форматирования, без пересмотра контента, но объём ощутимый (7×2 = 14 файлов, десятки функций).
os-detect/{vue,react}.md — тоже на отменённом паттерне №2, но это не такой прямой фикс, как казалось на первый взгляд — см. пункт 3 в разделе «Решение» ниже: они держат 5 composables/hooks на одной странице, что не описано буквально ни паттерном №1, ни №3.
Решение (2026-09-10)
- Формат подтверждён — голая строка типа + проза, без
Parameters/Returnsкак отдельных заголовков (вариант Б из этого файла). Плюс уточнение, которого не было в черновике: два варианта раскладки в зависимости от того, нужна ли тематическая группировка (А — без группировки, каждая функция получает человекочитаемый##; Б — с группировкой, категория человекочитаема, функция внутри — сырой###). Обе раскладки и обоснование через живую проверкуoutline-механики сайдбара — вdocs-template.md, раздел «Документирование функции». - Ретрофит
color-value-tools(7 файлов × 2 локали) — не начат, отдельная задача, ждёт своей очереди. os-detect/{vue,react}.md— решено: правило заголовков не завязано на архетип (функция vs composable), только на механикуoutline-сайдбара. «5 тонких composables без естественной категории на одной странице» — это вариант А (без группировки), применённый к composables: каждый получает свой человекочитаемый##+ точный идентификатор жирной строкой под заголовком, страница не обязана дробиться на 5 отдельных Composables-страниц. Формулировка — вdocs-template.md.
Полный список файлов на исправление (аудит 2026-09-10)
Регулярным поиском по всем гайд-страницам (H2, начинающиеся с необязательного обратного апострофа, затем именем функции и открывающей скобкой) найдены все сырые H2-заголовки вида «сигнатура функции» за пределами color-value-tools (уже исправлен) и os-detect/api-reference.md (уже исправлен). Легитимные исключения (не трогать) — имена компонентов в угловых скобках и PascalCase-классы/типы (<WorkerActivityPanel>, ContainerState) — уже читаются как существительные по правилу docs-template про компоненты.
Оба типа фикса: (заголовок) — сырой ## → человекочитаемый + жирная строка идентификатора под ним; (блок) — если формат тела ещё bullet-list Takes:/Returns:, перевести на голую строку типа + проза.
| Пакет | Файл | Заголовков | Блок-формат | Вариант |
|---|---|---|---|---|
| os-detect | vue.md, react.md | 5+5 | исправлено (bullet → вариант А) | А, без группировки |
| responsive-media | vue-integration.md | 3 (+1 доп. useResponsive<T>()) | исправлено (заголовок) | А |
| responsive-media | react-integration.md | 3 (+1 доп. useResponsive<T>()) | исправлено (заголовок) | А |
| responsive-media | subscription-api.md | 8 | исправлено (заголовок) | А |
| responsive-media | utilities.md | 9 (+1 доп. getState<T>()) | исправлено (заголовок), блок был эталонным | А |
| responsive-media | core-concepts.md | 1 | исправлено (заголовок) | А |
| rest-pipeline-js | vue-integration.md | 7 | исправлено (заголовок) | А |
| rest-pipeline-js | react-integration.md | 7 | исправлено (заголовок) | А |
| rest-pipeline-js | testing.md | 1 | исправлено (заголовок) | А |
| rest-pipeline-js | orchestrator.md | 2 из ~16 | исправлено (заголовок) | А (точечно) |
| vue-worker-kit | worker-pool.md | 1 | исправлено (заголовок) | А (компаньон-абзац) |
| vue-worker-kit | devtools.md | 1 | исправлено (заголовок) | А |
| vue-error-boundary-kit | nuxt.md | 1 | исправлено (заголовок) | А |
| vue-command-palette | registering-commands.md | 2 | исправлено (заголовок) | А |
| vue-feature-toggles | adapters.md | 3 | исправлено (заголовок) | А |
RU-версии каждого файла — то же самое (идентификаторы функций не переводятся, структура зеркальна EN).
Порядок выполнения: os-detect (оба фикса сразу) → responsive-media → rest-pipeline-js → vue-worker-kit → vue-error-boundary-kit → vue-command-palette → vue-feature-toggles. После каждого пакета: npx prettier --write, в конце — npm run build + grep-проверка (ноль - **Takes:**/сырых ##-сигнатур) + CDP-скриншоты выборочно.