doc: explicitly state the contracts of Stack and GuardedStack.

src/generator.rs

@@ -87,6 +87,8 @@ pub struct Generator<Input: Send, Output: Send, Stack: stack::Stack> {
 impl<Input, Output, Stack> Generator<Input, Output, Stack>
     where Input: Send, Output: Send, Stack: stack::Stack {
   /// Creates a new generator.
+  ///
+  /// See also the [contract](../trait.GuardedStack.html) that needs to be fulfilled by `stack`.
   pub fn new<F>(stack: Stack, f: F) -> Generator<Input, Output, Stack>
       where Stack: stack::GuardedStack,
             F: FnOnce(&mut Yielder<Input, Output, Stack>, Input) + Send {
@@ -98,6 +100,8 @@ impl<Input, Output, Stack> Generator<Input, Output, Stack>
   /// This function is unsafe because the generator function can easily violate
   /// memory safety by overflowing the stack. It is useful in environments where
   /// guarded stacks do not exist, e.g. in absence of an MMU.
+  ///
+  /// See also the [contract](../trait.Stack.html) that needs to be fulfilled by `stack`.
   pub unsafe fn unsafe_new<F>(stack: Stack, f: F) -> Generator<Input, Output, Stack>
       where F: FnOnce(&mut Yielder<Input, Output, Stack>, Input) + Send {
     unsafe extern "C" fn generator_wrapper<Input, Output, Stack, F>(env: usize) -> !

src/stack.rs

@@ -7,6 +7,15 @@
 //! Traits for stacks.
 
 /// A trait for objects that hold ownership of a stack.
+///
+/// To preserve memory safety, an implementation of this trait must fulfill
+/// the following contract:
+///
+///   * The base of the stack must be aligned to a platform-specific boundary.
+///   * Every address between the base and the limit must be readable and writable.
+///
+/// On any platform supported by libfringe, it is safe to align the stack to a 16-byte boundary.
+/// The platform ABI document lists the specific alignment requirement.
 pub trait Stack {
   /// Returns the base of the stack.
   /// On all modern architectures, the stack grows downwards,
@@ -20,6 +29,9 @@ pub trait Stack {
 
 /// A marker trait for `Stack` objects with a guard page.
 ///
-/// A guarded stack must guarantee that any access of data at addresses `limit()` to
+/// To preserve memory safety, an implementation of this trait must fulfill
-/// `limit().offset(4096)` will abnormally terminate the program.
+/// the following contract, in addition to the [contract](trait.Stack.html) of `Stack`:
+///
+///   * Any access of data at addresses `limit()` to `limit().offset(4096)` must
+///     abnormally terminate, at least, the thread that performs the access.
 pub unsafe trait GuardedStack {}