Для кого вы пишете?
Для коллег, соавторов, в основном молчаливых пользователей API или только для себя?
// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
// эксперт пишет для экспертов
/// Канонизирует MIR для анализатора заимствований.
///
/// Этот проход гарантирует, что все заимствования соответствуют ограничениям NLL-Polonius
/// до перехода к трансляции MIR в LLVM IR.
pub fn canonicalize_mir(mir: &mut Mir) {
// ...
}
// эксперт пишет для новичков
/// Подготавливает промежуточное представление среднего уровня (MIR) для анализа заимствований.
///
/// Анализатор заимствований работает с упрощённой «канонической» формой MIR.
/// Эта функция выполняет такое преобразование. Оно является предварительным условием для
/// последних этапов генерации кода.
///
/// Подробнее о промежуточных представлениях Rust см.
/// [rustc-dev-guide](https://rustc-dev-guide.rust-lang.org/mir/index.html).
pub fn canonicalize_mir(mir: &mut Mir) {
// ...
}-
Справка: проклятие знания — когнитивное искажение, при котором эксперты полагают, что у других такой же уровень знаний и такой же взгляд на вещи.
-
Мотивация: ваш читатель не обладает таким же уровнем знаний и не смотрит на вещи так же, как вы. Не пишите для людей, похожих на вас, пишите для других.
-
Непреднамеренное написание для себя может привести к тому, что люди не поймут мысль или понятие, которое вы хотите донести.
-
Представьте себе версию себя или других людей, которых вы знаете, которым трудно найти практическую информацию при чтении документации.
Держите этого человека в уме, когда думаете о том, какие части кодовой базы нуждаются во внимании в doc-комментариях.
-
Для кого вы пишете?
-
Также представьте себе версию себя или других людей, которым трудно найти важные детали в запутанных, объёмных doc-комментариях. Не давайте слишком много информации.
-
Всегда спрашивайте себя: мешает ли эта документация пользователю API? Может ли он быстро понять, что ему нужно, или найти, где это может понадобиться?
-
Всегда учитывайте: эксперты тоже читают документацию API. Doc-комментарии могут быть не лучшим местом для объяснения основ вашей предметной области. В таком случае укажите направление (signpost) и назовите ключевые понятия (name-drop). Направьте людей к подробной документации.