ドキュメントエイリアスのポリシー

Rust のドキュメントでは、#[doc(alias = "name")] という構文を使用して、任意の宣言（関数、型、定数など）にエイリアスを追加できます。私たちは、人々が探しているものを見つけやすくするためにドキュメントエイリアスを使用しつつ、それらのエイリアスを保守しやすく価値の高いものにしておきたいと考えています。このポリシーでは、ドキュメントエイリアスを追加するケースと、それらのエイリアスを省くケースについて概説します。

• 人々がその用語をドキュメント検索で検索するかもしれないと合理的に期待できなければなりません。Rust のドキュメントが提供するのは名前検索であり、全文検索ではありません。そのため、人々がもっともらしい名前を検索する可能性はあると考えていますが、より一般的なドキュメント検索については Web 検索エンジンを使うと想定しています。
  • 関連事項: 人々が現在、自分のよく知っている任意の言語に由来する言語固有の名前を Rust のドキュメントで検索しているとは考えておらず、またそれを新しいドキュメント検索機能として追加したくもありません。あなたのお気に入りの言語に基づくエイリアスは追加しないでください。そのような対応関係は、別個のガイドやリファレンスに置くべきです。一方で、人々が Rust に存在すると合理的に期待できる関数（たとえばシステム関数や C ライブラリ関数）について、Rust ではその関数が何と呼ばれているのかを知ろうとして、その Rust 名を探す可能性はあると考えています。
• 提案されたエイリアスは、その宣言に対して私たちがもっともらしく使っていた可能性のある名前でなければなりません。たとえば、create_dir に対する mkdir、remove_dir に対する rmdir、count_ones に対する popcnt と popcount、mode に対する umask などです。これは、誰かがその名前を検索し、それを見つけられると期待する（「Rust では mkdir を何と呼んだのか」）という合理的な期待につながります。
• エイリアスには、エイリアス化された名前の正確な類似物である明らかな単一の対象がなければなりません。同じエイリアスを複数の宣言に追加することはありません。（同じ関数の const 版と非 const 版は問題ありません。）また、多少似ているだけ、または関連しているだけの関数にエイリアスを追加することもありません。
• エイリアスは、既存の宣言の実際の名前と衝突してはなりません。
• stdarch の特別なケースとして、正確なアセンブリ命令名から対応する組み込み関数へのエイリアスは、他の名前と衝突しない限り歓迎されます。