Рекомендации по разработке на Kotlin — KDoc для публичного API

/**
 * Загружает профиль пользователя по идентификатору.
 *
 * Функция обращается к удалённому API и кэширует результат.
 * При ошибке сети возвращает данные из кэша, если они доступны.
 *
 * @param userId уникальный идентификатор пользователя
 * @param forceRefresh игнорировать кэш и загрузить свежие данные
 * @return профиль пользователя или ошибку загрузки
 */
suspend fun loadUserProfile(
    userId: UserId,
    forceRefresh: Boolean = false
): Result<UserProfile, LoadError> { /* реализация */ }