second round of documentation

src/context/mod.rs

@@ -70,6 +70,8 @@ fn init_contexts() -> RwLock<ContextList> {
 
 /// Get the global schemes list, const
 pub fn contexts() -> RwLockReadGuard<'static, ContextList> {
+    //call once will init_contexts only once during the kernel's exececution, otherwise it will return the current context via a
+    //cache.
     CONTEXTS.call_once(init_contexts).read()
 }
 

src/syscall/mod.rs

@@ -170,6 +170,11 @@ pub fn syscall(a: usize, b: usize, c: usize, d: usize, e: usize, f: usize, bp: u
     }
     */
 
+    // The next lines set the current syscall in the context struct, then once the inner() function
+    // completes, we set the current syscall to none.
+    //
+    // When the code below falls out of scope it will release the lock
+    // see the spin crate for details
     {
         let contexts = ::context::contexts();
         if let Some(context_lock) = contexts.current() {

src/syscall/time.rs

@@ -16,7 +16,9 @@ pub fn clock_gettime(clock: usize, time: &mut TimeSpec) -> Result<usize> {
     Ok(0)
 }
 
+/// Nanosleep will sleep by switching the current context
 pub fn nanosleep(req: &TimeSpec, rem_opt: Option<&mut TimeSpec>) -> Result<usize> {
+    //start is a tuple of (seconds, nanoseconds)
     let start = time::monotonic();
     let sum = start.1 + req.tv_nsec as u64;
     let end = (start.0 + req.tv_sec as u64 + sum / 1_000_000_000, sum % 1_000_000_000);