Рекомендации для авторов библиотек по созданию информативной документации

Подготовьте исчерпывающую документацию

В вашей библиотеке должно быть достаточно документации, чтобы пользователи могли начать её использовать с минимальными усилиями. Документация должна включать:

• Руководство «С чего начать»

• Подробное описание API

• Развёрнутые примеры для распространённых сценариев использования (также известные как рецепты)

• Ссылки на такие ресурсы, как блоги, статьи, вебинары и записи конференционных докладов

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

По возможности предоставьте отдельную версию документации для каждой поддерживаемой версии библиотеки. Так пользователи не будут просматривать устаревшую или слишком новую информацию. Если это невозможно, чётко пометьте разделы документации, относящиеся к переработанным частям API.

Создайте портреты пользователей

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

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

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

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

По возможности приводите примеры

Документация с примерами — один из самых экономичных способов объяснить пользователям основные понятия. По возможности приводите простые и понятные примеры кода, которые помогают объяснить или продемонстрировать рассматриваемую тему или концепцию.

Формат документации KDoc позволяет использовать в комментариях встроенную разметку Markdown. Добавляйте в комментарии встроенные фрагменты кода, чтобы показать, как пользоваться API. Пример можно найти в исходном коде и сформированной документации тестовых диспетчеров библиотеки корутин.

Такие примеры избавляют от необходимости писать длинные описания ожидаемых входных данных, возможных результатов и сценариев сбоев. Однако контекст каждого примера и условия его применимости должны быть ясны. Просто собрать в папке примеры программ без комментариев — это не документация.

Подробно документируйте API

Каждую поддерживаемую точку входа API следует документировать с помощью KDoc.

Система генерации документации для Kotlin Dokka по умолчанию включает в результаты только публичные объявления. Как отмечено в разделе «Простота», следует свести публичный API к минимуму и удалить публичные точки входа, к которым вы не хотите предоставлять пользователям доступ. Если вы не можете скрыть некоторые API от пользователей, изменив их видимость, исключите их из документации с помощью директивы suppress.

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

Например, не пишите «принимает String и возвращает Connection», а лучше скажите: «Пытается подключиться к базе данных, указанной во входной строке, возвращает Connection в случае успеха и выбрасывает ConnectionTimeoutException в противном случае».

Опишите ожидаемые значения каждого входного параметра и поведение функции при разных входных данных. Объясните диапазон допустимых значений и то, что происходит при передаче недопустимых значений. Например, если в качестве строки ожидается URL, опишите, что произойдёт, если строка окажется пустой или некорректной, будет использовать неподдерживаемый протокол либо указывать на несуществующее местоположение.

Документируйте каждое исключение, которое может выбросить точка входа API. Обсудите условия сбоя в общем описании, а раздел об исключениях используйте для подробной информации. Это повышает удобочитаемость и помогает читателю сосредоточиться на главном. Включайте такую информацию непосредственно в общее описание. По возможности приводите примеры использования — они также помогают пользователям понять, как правильно пользоваться API.

Документируйте параметры-лямбды

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

Во-первых, опишите, что произойдёт, если лямбда выбросит исключение. Рассмотрите следующие вопросы:

• Это приведёт к немедленному сбою, лямбда будет вызываться повторно или предусмотрено резервное поведение?

• Если вызывающая функция должна завершиться, выбросит ли она исключение из лямбды повторно или выбросит другое?

• Если исключение будет другим, будет ли оно содержать исходное исключение?

Кроме того, если функция не объявлена как inline, опишите особенности поведения, связанные с параллельным выполнением. Обязательно рассмотрите следующее:

• Будет ли лямбда вызвана в том же потоке, что и вызывающий код?

• Если лямбда будет вызвана не в том же потоке, что и вызывающий код, в каком потоке (или пуле потоков) она будет выполняться?

• Могут ли несколько копий лямбды выполняться параллельно?

• Какие ещё задачи могут выполняться в этом потоке?

• Может ли пользователь указать поток, который будет использовать библиотека?

• Если вызывается несколько лямбд, какие гарантии предоставляются относительно порядка их выполнения?

Используйте явные ссылки в документации

Точки входа API редко бывают полностью независимыми от других возможностей библиотеки. Обычно вызовы нужно выполнять в определённой последовательности, для выполнения конкретной задачи есть несколько вариантов, а точки входа для связанных задач используются похожим образом. Например, функции format и parse дополняют друг друга.

Используйте тег @see или внутренние ссылки, чтобы явно обозначить эти связи в документации. Это поможет читателю объединить информацию в смысловые группы и составить более целостную мысленную карту библиотеки.

По возможности предоставляйте всю необходимую информацию

Описывая допустимые входные данные, легко ограничиться ссылкой на соответствующий стандарт, например на стандарт W3C, IEEE или Консорциума Unicode. Такие ссылки могут быть полезны, но читателю не должно приходиться обращаться к внешней спецификации, чтобы узнать основные сведения, например набор символов пробела.

По возможности документация должна быть самодостаточной. Она должна содержать достаточно информации, чтобы пользователь понимал типичные способы использования каждой точки входа API. Для редких граничных случаев, которые не встречаются при обычном использовании, можно дать ссылку на внешние документы.

Используйте простой язык

При создании документации важно использовать простой и понятный язык. Так содержание будет доступно широкой аудитории, в том числе тем, для кого английский не является родным языком. Избегайте сложных слов, жаргона, латинских выражений и идиом, которые могут сбить читателей с толку. Вместо этого используйте ясные формулировки и короткие предложения.

Простой язык также упрощает перевод документации при необходимости. Ясный и однозначный текст снижает риск неправильного толкования и повышает удобочитаемость.

Что дальше

Если вы ещё не ознакомились с этими страницами, рекомендуем сделать это:

• Изучите стратегии снижения мысленной сложности на странице «Снижение мысленной сложности».

• Узнайте о поддержании обратной совместимости на странице «Обратная совместимость».