update docs

Author: imsut

docs/print.html

@@ -333,85 +333,165 @@ <h1 class="menu-title"></h1>
 to declare that the implementation of that trait has adhered to whatever
 contracts the trait's documentation requires.
 -->
-<p>The standard library has a number of unsafe functions, including:</p>
+<p>コードブロックに使われた <code>unsafe</code> は、そのブロックで呼ばれている危険な関数が要求する契約は守られていて、コードが信頼出来る事を意味します。<code>unsafe</code> を trait の実装に使うと、その実装が trait のドキュメントに書かれている契約に準拠している事を示します。</p>
+<!--
+The standard library has a number of unsafe functions, including:
+-->
+<p>標準ライブラリにはいくつもの危険な関数があります。例えば、</p>
+<!--
+* `slice::get_unchecked`, which performs unchecked indexing, allowing
+  memory safety to be freely violated.
+* `mem::transmute` reinterprets some value as having a given type, bypassing
+  type safety in arbitrary ways (see [conversions] for details).
+* Every raw pointer to a sized type has an intrinstic `offset` method that
+  invokes Undefined Behavior if the passed offset is not "in bounds" as
+  defined by LLVM.
+* All FFI functions are `unsafe` because the other language can do arbitrary
+  operations that the Rust compiler can't check.
+-->
 <ul>
-<li><code>slice::get_unchecked</code>, which performs unchecked indexing, allowing
-memory safety to be freely violated.</li>
-<li><code>mem::transmute</code> reinterprets some value as having a given type, bypassing
-type safety in arbitrary ways (see <a href="conversions.html">conversions</a> for details).</li>
-<li>Every raw pointer to a sized type has an intrinstic <code>offset</code> method that
-invokes Undefined Behavior if the passed offset is not &quot;in bounds&quot; as
-defined by LLVM.</li>
-<li>All FFI functions are <code>unsafe</code> because the other language can do arbitrary
-operations that the Rust compiler can't check.</li>
+<li><code>slice::get_unchecked</code> は未チェックのインデックス参照を実行します。自由自在にメモリ安全性に違反できます。</li>
+<li><code>mem::transmute</code> は、型安全の仕組みを好きなようにすり抜けて、ある値が特定の型であると再解釈します（詳細は <a href="conversions.html">変換</a> をみてください）。</li>
+<li>サイズが確定している型の生のポインタには、固有の <code>offset</code> メソッドがあります。渡されたオフセットが LLVM が定める &quot;境界内&quot; になければ、未定義の挙動を引き起こします。</li>
+<li>すべての FFI 関数は <code>unsafe</code> です。なぜなら Rust コンパイラは、他の言語が実行するどんな操作もチェックできないからです。</li>
 </ul>
-<p>As of Rust 1.0 there are exactly two unsafe traits:</p>
+<!--
+As of Rust 1.0 there are exactly two unsafe traits:
+-->
+<p>Rust 1.0 現在、危険な traits は 2 つしかありません。</p>
+<!--
+* `Send` is a marker trait (a trait with no API) that promises implementors are
+  safe to send (move) to another thread.
+* `Sync` is a marker trait that promises threads can safely share implementors
+  through a shared reference.
+  -->
 <ul>
-<li><code>Send</code> is a marker trait (a trait with no API) that promises implementors are
-safe to send (move) to another thread.</li>
-<li><code>Sync</code> is a marker trait that promises threads can safely share implementors
-through a shared reference.</li>
+<li><code>Send</code> は API を持たないマーカー trait で、実装された型が他のスレッドに安全に送れる（move できる）ことを約束します。</li>
+<li><code>Sync</code> もマーカー trait で、この trait を実装した型は、共有リファレンスを使って安全に複数のスレッドで共有できる事を約束します。</li>
 </ul>
-<p>Much of the Rust standard library also uses Unsafe Rust internally, although
+<!--
+Much of the Rust standard library also uses Unsafe Rust internally, although
 these implementations are rigorously manually checked, and the Safe Rust
-interfaces provided on top of these implementations can be assumed to be safe.</p>
-<p>The need for all of this separation boils down a single fundamental property
-of Safe Rust:</p>
-<p><strong>No matter what, Safe Rust can't cause Undefined Behavior.</strong></p>
-<p>The design of the safe/unsafe split means that Safe Rust inherently has to
+interfaces provided on top of these implementations can be assumed to be safe.
+-->
+<p>また、多くの Rust 標準ライブラリは内部で危険な Rust を使っています。ただ、標準ライブラリの
+実装はプログラマが徹底的にチェックしているので、危険な Rust の上に実装された安全な Rust は安全であると仮定して良いでしょう。</p>
+<!--
+The need for all of this separation boils down a single fundamental property
+of Safe Rust:
+<p><strong>No matter what, Safe Rust can't cause Undefined Behavior.</strong>
+--&gt;</p>
+<p>このように分離する目的は、結局のところ、安全な Rust のたった一つの基本的な性質にあります。</p>
+<p><strong>どうやっても、安全な Rust では未定義な挙動を起こせない。</strong></p>
+<!--
+The design of the safe/unsafe split means that Safe Rust inherently has to
 trust that any Unsafe Rust it touches has been written correctly (meaning
 the Unsafe Rust actually maintains whatever contracts it is supposed to
 maintain). On the other hand, Unsafe Rust has to be very careful about
-trusting Safe Rust.</p>
-<p>As an example, Rust has the <code>PartialOrd</code> and <code>Ord</code> traits to differentiate
-between types which can &quot;just&quot; be compared, and those that provide a total
+trusting Safe Rust.
+-->
+<p>このように安全と危険の分けると、安全な Rust は、自分が利用する危険な Rust が正しく書かれている事、
+つまり危険な Rust がそれが守るべき契約を実際に守っている事、を本質的に信頼しなくてはいけません。
+逆に、危険な Rust は安全な Rust を注意して信頼しなくてはいけません。</p>
+<!--
+As an example, Rust has the `PartialOrd` and `Ord` traits to differentiate
+between types which can "just" be compared, and those that provide a total
 ordering (where every value of the type is either equal to, greater than,
 or less than any other value of the same type). The sorted map type
-<code>BTreeMap</code> doesn't make sense for partially-ordered types, and so it
-requires that any key type for it implements the <code>Ord</code> trait. However,
-<code>BTreeMap</code> has Unsafe Rust code inside of its implementation, and this
-Unsafe Rust code cannot assume that any <code>Ord</code> implementation it gets makes
-sense. The unsafe portions of <code>BTreeMap</code>'s internals have to be careful to
-maintain all necessary contracts, even if a key type's <code>Ord</code> implementation
-does not implement a total ordering.</p>
-<p>Unsafe Rust cannot automatically trust Safe Rust. When writing Unsafe Rust,
+`BTreeMap` doesn't make sense for partially-ordered types, and so it
+requires that any key type for it implements the `Ord` trait. However,
+`BTreeMap` has Unsafe Rust code inside of its implementation, and this
+Unsafe Rust code cannot assume that any `Ord` implementation it gets makes
+sense. The unsafe portions of `BTreeMap`'s internals have to be careful to
+maintain all necessary contracts, even if a key type's `Ord` implementation
+does not implement a total ordering.
+-->
+<p>例えば、Rust には <code>PartialOrd</code> trait と <code>Ord</code> trait があり、単に比較可能な型と全順序が
+定義されている型（任意の値が同じ型の他の値と比べて等しいか、大きいか、小さい）とを区別します。
+順序つきマップの <code>BTreeMap</code> は半順序の型には使えないので、キーとして使われる型が <code>Ord</code> trait を
+実装している事を要求します。
+しかし <code>BTreeMap</code> の実装は危険な Rust が使っていて、危険な Rust は渡された <code>Ord</code> の実装が
+適切であるとは仮定できません。
+<code>BTreeMap</code> 内部の危険な部分は、キー型の <code>Ord</code> の実装が全順序ではない場合でも、必要な契約が
+すべて守られるよう注意深く書かれなくてはいけません。</p>
+<!--
+Unsafe Rust cannot automatically trust Safe Rust. When writing Unsafe Rust,
 you must be careful to only rely on specific Safe Rust code, and not make
 assumptions about potential future Safe Rust code providing the same
-guarantees.</p>
-<p>This is the problem that <code>unsafe</code> traits exist to resolve. The <code>BTreeMap</code>
+guarantees.
+-->
+<p>危険な Rust は安全な Rust を無意識には信頼できません。危険な Rust コードを書くときには、
+安全な Rust の特定のコードのみに依存する必要があり、
+安全な Rust が将来にわたって同様の安全性を提供すると仮定してはいけません。</p>
+<!--
+This is the problem that `unsafe` traits exist to resolve. The `BTreeMap`
 type could theoretically require that keys implement a new trait called
-<code>UnsafeOrd</code>, rather than <code>Ord</code>, that might look like this:</p>
+`UnsafeOrd`, rather than `Ord`, that might look like this:
+-->
+<p>この問題を解決するために <code>unsafe</code> な trait が存在します。理論上は、<code>BTreeMap</code> 型は
+キーが <code>Ord</code> ではなく、新しい trait <code>UnsafeOrd</code> を実装する事を要求する事ができます。
+このようなコードになるでしょう。</p>
 <pre><code class="language-rust">use std::cmp::Ordering;
 
 unsafe trait UnsafeOrd {
     fn cmp(&amp;self, other: &amp;Self) -&gt; Ordering;
 }
 </code></pre>
-<p>Then, a type would use <code>unsafe</code> to implement <code>UnsafeOrd</code>, indicating that
+<!--
+Then, a type would use `unsafe` to implement `UnsafeOrd`, indicating that
 they've ensured their implementation maintains whatever contracts the
 trait expects. In this situation, the Unsafe Rust in the internals of
-<code>BTreeMap</code> could trust that the key type's <code>UnsafeOrd</code> implementation is
+`BTreeMap` could trust that the key type's `UnsafeOrd` implementation is
 correct. If it isn't, it's the fault of the unsafe trait implementation
-code, which is consistent with Rust's safety guarantees.</p>
-<p>The decision of whether to mark a trait <code>unsafe</code> is an API design choice.
+code, which is consistent with Rust's safety guarantees.
+-->
+<p>この場合、<code>UnsafeOrd</code> を実装する型は、この trait が期待する契約に準拠している事を示すために
+<code>unsafe</code> キーワードを使うことになります。
+この状況では、<code>BTreeMap</code> 内部の危険な Rust は、キー型が <code>UnsafeOrd</code> を正しく実装していると
+信用する事ができます。もしそうで無ければ、それは trait の実装の問題であり、
+これは Rust の安全性の保証と一致しています。</p>
+<!--
+The decision of whether to mark a trait `unsafe` is an API design choice.
 Rust has traditionally avoided marking traits unsafe because it makes Unsafe
-Rust pervasive, which is not desirable. <code>Send</code> and <code>Sync</code> are marked unsafe
-because thread safety is a <em>fundamental property</em> that unsafe code can't
+Rust pervasive, which is not desirable. `Send` and `Sync` are marked unsafe
+because thread safety is a *fundamental property* that unsafe code can't
 possibly hope to defend against in the way it could defend against a bad
-<code>Ord</code> implementation. The decision of whether to mark your own traits <code>unsafe</code>
-depends on the same sort of consideration. If <code>unsafe</code> code cannot reasonably
+`Ord` implementation. The decision of whether to mark your own traits `unsafe`
+depends on the same sort of consideration. If `unsafe` code cannot reasonably
 expect to defend against a bad implementation of the trait, then marking the
-trait <code>unsafe</code> is a reasonable choice.</p>
-<p>As an aside, while <code>Send</code> and <code>Sync</code> are <code>unsafe</code> traits, they are
+trait `unsafe` is a reasonable choice.
+-->
+<p>trait に <code>unsafe</code> をつけるかどうかは API デザインにおける選択です。
+Rust では従来 <code>unsafe</code> な trait を避けてきました。そうしないと危険な Rust が
+蔓延してしまい、好ましくないからです。
+<code>Send</code> と <code>Sync</code> が <code>unsafe</code> となっているのは、スレッドの安全性が <em>基本的な性質</em> であり、
+間違った <code>Ord</code> の実装に対して危険なコードが防衛できるのと同様の意味では防衛できないからです。
+あなたが宣言した trait を <code>unsafe</code> とマークするかどうかも、同じようにじっくりと考えてください。
+もし <code>unsafe</code> なコードがその trait の間違った実装から防御することが合理的に不可能であるなら、
+その trait を <code>unsafe</code> とするのは合理的な選択です。</p>
+<!--
+As an aside, while `Send` and `Sync` are `unsafe` traits, they are
 automatically implemented for types when such derivations are provably safe
-to do. <code>Send</code> is automatically derived for all types composed only of values
-whose types also implement <code>Send</code>. <code>Sync</code> is automatically derived for all
-types composed only of values whose types also implement <code>Sync</code>.</p>
-<p>This is the dance of Safe Rust and Unsafe Rust. It is designed to make using
+to do. `Send` is automatically derived for all types composed only of values
+whose types also implement `Send`. `Sync` is automatically derived for all
+types composed only of values whose types also implement `Sync`.
+-->
+<p>余談ですが、<code>unsafe</code> な trait である <code>Send</code> と <code>Sync</code> は、それらを実装する事が安全だと
+実証可能な場合には自動的に実装されます。
+<code>Send</code> は、<code>Send</code> を実装した型だけから構成される型に対して、自動的に実装されます。
+<code>Sync</code> は、<code>Sync</code> を実装した型だけから構成される型に対して、自動的に実装されます。</p>
+<!--
+This is the dance of Safe Rust and Unsafe Rust. It is designed to make using
 Safe Rust as ergonomic as possible, but requires extra effort and care when
 writing Unsafe Rust. The rest of the book is largely a discussion of the sort
 of care that must be taken, and what contracts it is expected of Unsafe Rust
-to uphold.</p>
+to uphold.
+-->
+<p>これが安全な Rust と危険な Rust のダンスです。
+これは、安全な Rust をできるだけ快適に使えるように、しかし危険な Rust を書くには
+それ以上の努力と注意深さが要求されるようなデザインになっています。
+この本の残りでは、どういう点に注意しなくはいけないのか、
+危険な Rust を維持するための契約とは何なのかを議論します。</p>
 <a class="header" href="#working-with-unsafe" name="working-with-unsafe"><h1>Working with Unsafe</h1></a>
 <p>Rust generally only gives us the tools to talk about Unsafe Rust in a scoped and
 binary manner. Unfortunately, reality is significantly more complicated than