Руководство по стилю справочника API: единый формат каждой записи

Что это такое

Справочная запись описывает одну функцию, конечную точку, тип или параметр настройки. Руководство по стилю справочных материалов — краткий внутренний документ, который задаёт для каждой записи разделы и их порядок, форму первого предложения и формулировки повторяющихся фактов. Цитируемое руководство Microsoft перечисляет разделы справочной статьи в фиксированном порядке: заголовок и описание, объявление или синтаксис, параметры, возвращаемое значение, замечания, пример, требования и дополнительные ссылки, а также исключения или коды ошибок там, где элемент может их выдавать. Для каждого параметра указывают тип данных и, где уместно, обязательность или необязательность, а описание не должно просто повторять имя элемента. Цитируемое руководство Google по комментариям для справочника API отмечает, что в сводные разделы и указатели попадает только первое предложение описания, поэтому в нём должна быть самая важная информация; при объявлении устаревшим необходимо указать замену. Цитируемый OpenAPI отделяет summary, краткое изложение действия операции, от более длинного description.

Почему это важно

Справочники читают поиском нужного, а не подряд. Читатель, узнавший, где в одной записи находится возвращаемое значение, ожидает найти его там же в следующей; агент, извлекающий параметры, опирается на ту же регулярность. Генерируемые справочники (из docstring, OpenAPI, комментариев документации) воспроизводят дисциплину исходного материала, поэтому руководство по стилю применяют к источнику.

Как применять

• Первое предложение: законченное высказывание о том, что делает элемент, в третьем лице, начинающееся с глагола («Возвращает …», «Создаёт …») и понятное само по себе в указателе.
• Параметры: имя, тип, обязательность или необязательность, значение по умолчанию, допустимый диапазон или формат и поведение на границе. Параметр без указанного значения по умолчанию имеет недокументированное поведение.
• Возвращаемое значение: тип, смысл и случаи пустого значения, null или отсутствия результата.
• Ошибки: по строке на условие в форме «условие: возникающая ошибка или возвращаемый статус»; дайте ссылку на общий формат ошибок.
• Замечания: гарантии порядка, идемпотентность, побочные эффекты, ограничения частоты, потокобезопасность. Ничего из того, что относится к учебному руководству.
• Пример: один минимальный исполняемый вызов с его выводом; по возможности поддерживайте его выполнение в CI.
• Устаревание: замена, версия, начиная с которой элемент устарел, и план удаления — в первом предложении.
• Терминология: для каждого понятия используйте предпочтительный термин глоссария и везде одинаковые единицы и форматы дат.

Подводные камни

Краткие описания, повторяющие имя («getUser: получает пользователя»). Описание реализации вместо контракта. Ограничения, изложенные только словами, которые валидатор проверяет иначе. Примеры, которые больше не запускаются. Разный порядок разделов у разных авторов — именно эту проблему и должно устранять руководство.