Избегаем избыточности
Имена и сигнатуры типов передают много информации; не повторяйте её в комментариях!
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// Повторяет информацию об имени и типе. Можно опустить!
/// Разбирает ipv4 из str. Возвращает Option для случаев ошибки.
fn parse_ip_addr_v4(input: &str) -> Option<IpAddrV4> { ... }
// Повторяет информацию, очевидную из имени поля. Можно опустить!
struct BusinessAsset {
/// Идентификатор клиента.
customer_id: u64,
}
// Сначала упоминается имя типа, так делать нельзя!
/// `ServerSynchronizer` --- оркестратор, который отправляет локальные правки [...]
struct ServerSynchronizer { ... }
// Лучше! Сосредоточено на назначении.
/// Отправляет локальные правки [...]
struct ServerSynchronizer { ... }
// Сначала упоминается имя функции, так делать нельзя!
/// `sync_to_server` отправляет локальные правки [...]
fn sync_to_server(...)
// Лучше! Сосредоточено на функции.
/// Отправляет локальные правки [...]
fn sync_to_server(...)-
Мотивация: документация, которая просто повторяет информацию об имени и сигнатуре, не даёт пользователю API ничего нового.
Кроме того, информация о сигнатуре может со временем измениться, а документация не будет обновлена соответственно!
-
Это понятная ловушка!
Наивный подход «всегда документируй свой код» следует этому совету буквально, но не его смыслу.
Некоторые инструменты могут требовать покрытия документацией; такую документацию исправить легко.
-
Учитывайте назначение разных видов документации:
-
Код библиотеки нужно документировать с учётом того, для чего он используется и насколько широк круг людей, которые пытаются его использовать.
-
Код приложения имеет более узкое назначение, поэтому может позволить себе быть проще и прямолинейнее.
-
-
Имя элемента — часть его документации.
Аналогично, сигнатура функции — часть её документации.
Поэтому некоторые аспекты элемента уже раскрыты, когда вы начинаете писать doc-комментарии!
Не повторяйте информацию ради пункта в списке.
-
Многие разделы стандартной библиотеки имеют минимальную документацию, потому что имени и типов достаточно для понимания.
Практическое правило: какой информации не хватает с точки зрения пользователя? Кроме имени, сигнатуры и несущественных деталей реализации.
-
Не объясняйте основы Rust или стандартной библиотеки. Считайте, что читатель имеет средний уровень владения самим языком. Сосредоточьтесь на документировании вашего API.
Например, если ваша функция возвращает
Result, не нужно объяснять, как работаютResultили оператор вопросительного знака.
Для дальнейшего изучения
-
Линт
#![warn(missing_docs)]может помочь обеспечить наличие doc-комментариев, но он создаёт большую нагрузку на разработчиков, что может привести к тому, что они будут писать комментарии низкого качества.Такой линт стоит включать, только если люди, поддерживающие проект, могут справляться с его требованиями, и обычно только для крейтов-библиотек, а не для кода приложений.