From aa364056fdd4f259f1d9b29f573db9cd864b5867 Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Sun, 17 Jul 2016 00:47:37 +0000
Subject: [PATCH] Add more documentation, and rephrase it elsewhere.

---
 src/context.rs | 14 +++++++-------
 src/os/mod.rs  |  9 +++++++--
 2 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/src/context.rs b/src/context.rs
index 98609d8..7572480 100644
--- a/src/context.rs
+++ b/src/context.rs
@@ -6,13 +6,13 @@ use stack;
 use debug;
 use arch;
 
-/// Context is the heart of libfringe.
-/// A context represents a saved thread of execution, along with a stack.
+/// Context holds a suspended thread of execution along with a stack.
+///
 /// It can be swapped into and out of with the swap method,
 /// and once you're done with it, you can get the stack back through unwrap.
 ///
-/// Every operation is unsafe, because libfringe can't make any guarantees
-/// about the state of the context.
+/// Every operation is unsafe, because no guarantees can be made about
+/// the state of the context.
 #[derive(Debug)]
 pub struct Context<Stack: stack::Stack> {
   stack:     Stack,
@@ -24,7 +24,7 @@ unsafe impl<Stack> Send for Context<Stack>
   where Stack: stack::Stack + Send {}
 
 impl<Stack> Context<Stack> where Stack: stack::Stack {
-  /// Create a new Context. When it is swapped into, it will call
+  /// Creates a new Context. When it is swapped into, it will call
   /// `f(arg)`, where `arg` is the argument passed to `swap`.
   pub unsafe fn new(stack: Stack, f: unsafe extern "C" fn(usize) -> !) -> Context<Stack> {
     let stack_id  = debug::StackId::register(&stack);
@@ -36,14 +36,14 @@ impl<Stack> Context<Stack> where Stack: stack::Stack {
     }
   }
 
-  /// Unwrap the context, returning the stack it contained.
+  /// Unwraps the context, returning the stack it contained.
   pub unsafe fn unwrap(self) -> Stack {
     self.stack
   }
 }
 
 impl<OldStack> Context<OldStack> where OldStack: stack::Stack {
-  /// Switch to in_ctx, saving the current thread of execution to out_ctx.
+  /// Switches to in_ctx, saving the current thread of execution to out_ctx.
   #[inline(always)]
   pub unsafe fn swap<NewStack>(old_ctx: *mut Context<OldStack>,
                                new_ctx: *const Context<NewStack>,
diff --git a/src/os/mod.rs b/src/os/mod.rs
index 70ccec4..e977c18 100644
--- a/src/os/mod.rs
+++ b/src/os/mod.rs
@@ -7,8 +7,9 @@ use stack;
 
 mod sys;
 
-/// This object represents a stack from the operating system's
-/// anonymous memory mapping facility, usually `mmap`.
+/// OsStack holds a stack allocated using the operating system's anonymous
+/// memory mapping facility.
+///
 /// The stack it provides comes with a guard page, which is not included
 /// in the stack limit.
 #[derive(Debug)]
@@ -20,6 +21,10 @@ pub struct Stack {
 unsafe impl Send for Stack {}
 
 impl Stack {
+  /// Allocates a new stack with at least `size` accessible bytes.
+  /// `size` is rounded up to an integral number of pages; `Stack::new(0)`
+  /// is legal and allocates the smallest possible stack, consisting
+  /// of one data page and one guard page.
   pub fn new(size: usize) -> Result<Stack, IoError> {
     let page_size = sys::page_size();