Как создать C# API Reference для библиотеки или Unity-плагина
Создайте полезный справочник C# API с публичными типами, сигнатурами, параметрами, примерами и ссылками на практические руководства и экспортируйте его в HTML.
Начните с поддерживаемого публичного API
API Reference должен описывать поверхность, предназначенную для пользователей, а не все детали реализации сборки. Определите поддерживаемые пространства имен, типы, члены, методы расширения, события и константы. Исключите внутренние вспомогательные элементы и устаревшие члены, если они не нужны для миграции.
Такая проверка часто обнаруживает случайно открытые члены и непоследовательные названия. Исправить эти проблемы до выпуска полезнее, чем создать красивую страницу для API, который не был спроектирован намеренно.
Опишите сведения, необходимые во время поиска
Каждому публичному типу нужно краткое назначение. Для вызываемого члена опишите поведение, параметры, результат, побочные эффекты, важные исключения и ограничения. У свойств указывайте единицы измерения, допустимый диапазон, значение по умолчанию и возможность изменения во время выполнения. Для событий объясняйте момент вызова и поток, если это важно.
Не повторяйте идентификатор другими словами. Фраза «получает тайм-аут» почти бесполезна, а «возвращает максимальное время ожидания ответа сервера в миллисекундах» отвечает на практический вопрос. Используйте одинаковые термины в описаниях, параметрах, примерах и руководствах.
Добавьте примеры, не превращая справочник в учебник
Короткие примеры объясняют создание объектов, жизненный цикл, обработку ошибок и сочетания, которые не видны из сигнатуры. Пусть каждый справочный пример фокусируется на одном типе или члене и по возможности компилируется. Длинные сквозные сценарии лучше вынести в руководства.
Создавайте ссылки в обе стороны. Руководство по загрузке данных должно ссылаться на используемые типы, а страницы этих типов — обратно на руководство. Тогда читатель сможет перейти от вопроса «как выполнить задачу?» к вопросу «какие значения принимает метод?» без потери контекста.
Сгенерируйте и проверьте API Reference
One File Docs поддерживает раздел api с JSON, созданным CSharpApiExtractor. Просмотрщик превращает структурированные данные в C# API Reference рядом с обычными страницами документации. Генерация устраняет повторяющуюся сборку страниц, но не заменяет редакторскую проверку.
Проверьте перегрузки, ограничения обобщенных типов, наследование, ссылки между типами, оформление кода, признаки устаревания и пропущенные описания. Найдите шаблонные фразы и недокументированные публичные члены. Покажите результат разработчику, который не участвовал в проектировании API.
Версионируйте справочник вместе со сборкой
Точный справочник от другой версии сборки все равно содержит неверные сведения. Генерируйте или обновляйте документацию из той же ревизии исходного кода, что и выпуск, указывайте версию продукта и архивируйте экспорт вместе с соответствующим пакетом.
Объедините API Reference с установкой, быстрым стартом, концепциями, обновлением и устранением неполадок. One File Docs экспортирует их одним HTML-файлом с поиском, который можно приложить к NuGet-пакету, SDK, настольной программе, Unity-ассету или GitHub Release.