Почему и что, а не как и где

Не документируйте несущественные детали, которые могут часто меняться.

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0

// плохо
/// Сохраняет запись `User` в базе данных Postgres.
///
/// Эта функция открывает новое соединение и начинает транзакцию. Она проверяет,
/// существует ли пользователь с данным ID, с помощью запроса `SELECT`. Если пользователь
/// не найден, выполняет `INSERT`.
///
/// # Errors
///
/// Возвращает ошибку, если любая операция с базой данных завершилась неудачно.  
pub fn save_user(user: &User) -> Result<(), db::Error> {
    // ...
}

// хорошо
/// Атомарно сохраняет запись пользователя.
///
/// # Errors
///
/// Возвращает ошибку `db::Error::DuplicateUsername`, если пользователь (с ключом из
/// поля `user.username`) уже существует.  
pub fn save_user(user: &User) -> Result<(), db::Error> {
    // ...
}