diff --git a/zircon-syscall/src/channel.rs b/zircon-syscall/src/channel.rs
index 69fcb4e9..76af55df 100644
--- a/zircon-syscall/src/channel.rs
+++ b/zircon-syscall/src/channel.rs
@@ -9,8 +9,8 @@ use {
 };
 
 impl Syscall<'_> {
-    /// Read a message from a channel.
     #[allow(clippy::too_many_arguments)]
+    /// Read/Receive a message from a channel.  
     pub fn sys_channel_read(
         &self,
         handle_value: HandleValue,
@@ -74,7 +74,7 @@ impl Syscall<'_> {
         }
         Ok(())
     }
-    /// Write a message to a channel.
+    /// Write a message to a channel.  
     pub fn sys_channel_write(
         &self,
         handle_value: HandleValue,
@@ -114,7 +114,7 @@ impl Syscall<'_> {
         channel.write(MessagePacket { data, handles })?;
         Ok(())
     }
-    /// Create a channel.
+    /// Create a new channel.   
     pub fn sys_channel_create(
         &self,
         options: u32,
@@ -134,6 +134,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
+    ///   
     pub async fn sys_channel_call_noretry(
         &self,
         handle_value: HandleValue,
@@ -210,7 +211,7 @@ impl Syscall<'_> {
             Err(ZxError::BAD_STATE)
         }
     }
-    /// Write a message to a channel.
+    /// Write a message to a channel.  
     pub fn sys_channel_write_etc(
         &self,
         handle: HandleValue,
diff --git a/zircon-syscall/src/cprng.rs b/zircon-syscall/src/cprng.rs
index 26e8aa1d..ffaaf98e 100644
--- a/zircon-syscall/src/cprng.rs
+++ b/zircon-syscall/src/cprng.rs
@@ -1,13 +1,16 @@
 use super::*;
 
-/// Draw random bytes from the kernel CPRNG.   
-/// This data should be suitable for cryptographic applications.  
-/// > Clients that require a large volume of randomness should consider using these bytes to seed a user-space random number generator for better performance.
 impl Syscall<'_> {
+    /// Draw random bytes from the kernel CPRNG.   
+    ///
+    /// This data should be suitable for cryptographic applications.  
+    ///
+    /// Clients that require a large volume of randomness should consider using these bytes to seed a user-space random number generator for better performance.
     pub fn sys_cprng_draw_once(&self, mut buf: UserOutPtr<u8>, len: usize) -> ZxResult {
         info!("cprng_draw_once: buf=({:?}; {:?})", buf, len);
         let mut res = vec![0u8; len];
-        kernel_hal::fill_random(&mut res); // Fill random bytes to the buffer
+        // Fill random bytes to the buffer
+        kernel_hal::fill_random(&mut res);
         buf.write_array(&res)?;
         Ok(())
     }
diff --git a/zircon-syscall/src/ddk.rs b/zircon-syscall/src/ddk.rs
index 59e5597e..6b70abc5 100644
--- a/zircon-syscall/src/ddk.rs
+++ b/zircon-syscall/src/ddk.rs
@@ -39,9 +39,10 @@ impl Syscall<'_> {
         Ok(())
     }
     /// Creates a new bus transaction initiator.  
-    /// iommu: HandleValue, a handle to an IOMMU   
-    /// options: u32, must be 0 (reserved for future definition of creation flags).  
-    /// bti_id: u64, a hardware transaction identifier for a device downstream of that IOMMU.  
+    ///
+    /// `iommu: HandleValue`, a handle to an IOMMU.   
+    /// `options: u32`, must be 0 (reserved for future definition of creation flags).  
+    /// `bti_id: u64`, a hardware transaction identifier for a device downstream of that IOMMU.  
     pub fn sys_bti_create(
         &self,
         iommu: HandleValue,
@@ -68,7 +69,7 @@ impl Syscall<'_> {
     }
 
     #[allow(clippy::too_many_arguments)]
-    /// Pin pages and grant devices access to them.
+    /// Pin pages and grant devices access to them.  
     pub fn sys_bti_pin(
         &self,
         bti: HandleValue,
@@ -112,7 +113,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Unpins pages that were previously pinned by ```zx_bti_pin()```
+    /// Unpins pages that were previously pinned by `zx_bti_pin()`.  
     pub fn sys_pmt_unpin(&self, pmt: HandleValue) -> ZxResult {
         info!("pmt.unpin: pmt={:#x}", pmt);
         let proc = self.thread.proc();
@@ -121,7 +122,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// ReleaseRs all quarantined PMTs for the given BTI.
+    /// Releases all quarantined PMTs for the given BTI.
     pub fn sys_bti_release_quarantine(&self, bti: HandleValue) -> ZxResult {
         info!("bti.release_quarantine: bti = {:#x}", bti);
         let proc = self.thread.proc();
@@ -130,6 +131,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
+    ///   
     pub fn sys_pc_firmware_tables(
         &self,
         resource: HandleValue,
@@ -176,7 +178,8 @@ impl Syscall<'_> {
     }
 
     /// Binds or unbinds an interrupt object to a port.   
-    /// The key used when binding the interrupt will be present in the key field of the ```zx_port_packet_t.```
+    ///
+    /// The key used when binding the interrupt will be present in the key field of the `zx_port_packet_t`.
     pub fn sys_interrupt_bind(
         &self,
         interrupt: HandleValue,
@@ -203,7 +206,7 @@ impl Syscall<'_> {
         }
     }
 
-    /// Triggers a virtual interrupt object.
+    /// Triggers a virtual interrupt object.  
     pub fn sys_interrupt_trigger(
         &self,
         interrupt: HandleValue,
@@ -222,7 +225,8 @@ impl Syscall<'_> {
     }
 
     /// Acknowledge an interrupt and re-arm it.  
-    /// causing it to be eligible to trigger again (and delivering a packet to the port it is bound to).
+    ///
+    /// This system call acknowledges an interrupt object, causing it to be eligible to trigger again (and delivering a packet to the port it is bound to).
     pub fn sys_interrupt_ack(&self, interrupt: HandleValue) -> ZxResult {
         info!("interupt.ack: interrupt={:?}", interrupt);
         let interrupt = self
@@ -232,14 +236,14 @@ impl Syscall<'_> {
         interrupt.ack()
     }
 
-    /// Destroys an interrupt object.
+    /// Destroys an interrupt object.  
     pub fn sys_interrupt_destroy(&self, interrupt: HandleValue) -> ZxResult {
         info!("interupt.destory: interrupt={:?}", interrupt);
         let interrupt = self.thread.proc().get_object::<Interrupt>(interrupt)?;
         interrupt.destroy()
     }
 
-    /// A blocking syscall which causes the caller to wait until an interrupt is triggered.
+    /// A blocking syscall which causes the caller to wait until an interrupt is triggered.  
     pub async fn sys_interrupt_wait(
         &self,
         interrupt: HandleValue,
diff --git a/zircon-syscall/src/debug.rs b/zircon-syscall/src/debug.rs
index 011f779f..682c3f03 100644
--- a/zircon-syscall/src/debug.rs
+++ b/zircon-syscall/src/debug.rs
@@ -2,10 +2,7 @@ use super::*;
 use zircon_object::dev::*;
 
 impl Syscall<'_> {
-    /// Write debug info to the serial port  
-    /// To use the zx_debug_write() function,   
-    /// you must specify ```kernel.enable-serial-syscalls=true``` or ```kernel.enable-serial-syscalls=output-only``` on the kernel command line.   
-    /// Otherwise, the function returns ZX_ERR_NOT_SUPPORTED.
+    /// Write debug info to the serial port.  
     pub fn sys_debug_write(&self, buf: UserInPtr<u8>, len: usize) -> ZxResult {
         info!("debug.write: buf=({:?}; {:#x})", buf, len);
         let data = buf.read_array(len)?;
@@ -13,7 +10,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Read debug info from the serial port
+    /// Read debug info from the serial port.  
     pub async fn sys_debug_read(
         &self,
         handle: HandleValue,
diff --git a/zircon-syscall/src/debuglog.rs b/zircon-syscall/src/debuglog.rs
index 92127d1f..7675ac69 100644
--- a/zircon-syscall/src/debuglog.rs
+++ b/zircon-syscall/src/debuglog.rs
@@ -4,7 +4,7 @@ use {
 };
 
 impl Syscall<'_> {
-    /// Create a kernel managed debuglog reader or writer;
+    /// Create a kernel managed debuglog reader or writer.    
     pub fn sys_debuglog_create(
         &self,
         rsrc: HandleValue,
@@ -32,7 +32,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Write log to debuglog Kernel
+    /// Write log entry to debuglog.   
     pub fn sys_debuglog_write(
         &self,
         handle_value: HandleValue,
@@ -62,7 +62,7 @@ impl Syscall<'_> {
     }
 
     #[allow(unsafe_code)]
-    /// Read log to debuglog Kernel
+    /// Read log entries from debuglog.  
     pub fn sys_debuglog_read(
         &self,
         handle_value: HandleValue,
diff --git a/zircon-syscall/src/exception.rs b/zircon-syscall/src/exception.rs
index 3bac3853..d1101fc3 100644
--- a/zircon-syscall/src/exception.rs
+++ b/zircon-syscall/src/exception.rs
@@ -52,7 +52,8 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Create a handle for the exception's thread.    
+    /// Create a handle for the exception's thread.
+    ///    
     /// The exception handle out will be filled with a new handle to the exception thread.  
     pub fn sys_exception_get_thread(
         &self,
@@ -69,9 +70,10 @@ impl Syscall<'_> {
     }
 
     /// Create a handle for the exception's process.  
-    /// The exception handle out will be filled with a new handle to the exception process.   
-    /// > Only available for job and process exception channels,     
-    /// > thread exceptions cannot access their parent process handles.  
+    ///
+    /// The exception handle out will be filled with a new handle to the exception process.    
+    /// > Only available for job and process exception channels.      
+    /// > Thread exceptions cannot access their parent process handles.    
     pub fn sys_exception_get_process(
         &self,
         exception: HandleValue,
diff --git a/zircon-syscall/src/fifo.rs b/zircon-syscall/src/fifo.rs
index e0b88e16..e93dbd0d 100644
--- a/zircon-syscall/src/fifo.rs
+++ b/zircon-syscall/src/fifo.rs
@@ -1,7 +1,7 @@
 use {super::*, zircon_object::ipc::Fifo};
 
 impl Syscall<'_> {
-    /// Creates a fifo, which is actually a pair of fifos of ```elem_count``` entries of ```elem_size``` bytes.
+    /// Creates a fifo, which is actually a pair of fifos of `elem_count` entries of `elem_size` bytes.
     pub fn sys_fifo_create(
         &self,
         elem_count: usize,
diff --git a/zircon-syscall/src/futex.rs b/zircon-syscall/src/futex.rs
index 7abb13be..3b0cb00a 100644
--- a/zircon-syscall/src/futex.rs
+++ b/zircon-syscall/src/futex.rs
@@ -2,8 +2,9 @@ use {super::*, zircon_object::task::ThreadState};
 
 impl Syscall<'_> {
     /// Wait on a futex.  
-    /// This system call function atomically verifies that ```value_ptr``` still contains the value ```current_value```  
-    /// and sleeps until the futex is made available by a call to ```zx_futex_wake```
+    ///  
+    /// This system call function atomically verifies that `value_ptr` still contains the value `current_value`   
+    /// and sleeps until the futex is made available by a call to `zx_futex_wake`  
     pub async fn sys_futex_wait(
         &self,
         value_ptr: UserInPtr<AtomicI32>,
@@ -32,7 +33,8 @@ impl Syscall<'_> {
             .await?;
         Ok(())
     }
-
+    /// Wake some waiters and requeue other waiters.   
+    ///   
     /// Wake some number of threads waiting on a futex, and move more waiters to another wait queue.
     pub fn sys_futex_requeue(
         &self,
@@ -73,7 +75,8 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Wake some number of threads waiting on a futex, optionally transferring ownership to the thread which was woken in the process.  
+    /// Wake some number of threads waiting on a futex.   
+    ///
     /// > Waking up zero threads is not an error condition. Passing in an unallocated address for value_ptr is not an error condition.
     pub fn sys_futex_wake(&self, value_ptr: UserInPtr<AtomicI32>, count: u32) -> ZxResult {
         info!("futex.wake: value_ptr={:?}, count={:#x}", value_ptr, count);
diff --git a/zircon-syscall/src/handle.rs b/zircon-syscall/src/handle.rs
index 69b87836..bfb370a8 100644
--- a/zircon-syscall/src/handle.rs
+++ b/zircon-syscall/src/handle.rs
@@ -1,8 +1,9 @@
 use {super::*, core::convert::TryFrom};
 
 impl Syscall<'_> {
-    /// Creates a duplicate of handle  
-    /// Referring to the same underlying object, with new access rights rights.
+    /// Creates a duplicate of handle.   
+    ///
+    /// Referring to the same underlying object, with new access rights rights.  
     pub fn sys_handle_duplicate(
         &self,
         handle_value: HandleValue,
@@ -32,7 +33,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Close a handle and reclaim the underlying object if no other handles to it exist.
+    /// Close a handle and reclaim the underlying object if no other handles to it exist.  
     pub fn sys_handle_close(&self, handle: HandleValue) -> ZxResult {
         info!("handle.close: handle={:?}", handle);
         if handle == INVALID_HANDLE {
@@ -43,7 +44,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Close a number of handles.
+    /// Close a number of handles.  
     pub fn sys_handle_close_many(
         &self,
         handles: UserInPtr<HandleValue>,
@@ -64,8 +65,9 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Creates a replacement for handle  
-    /// Referring to the same underlying object, with new access rights rights.
+    /// Creates a replacement for handle.  
+    ///
+    /// Referring to the same underlying object, with new access rights rights.  
     pub fn sys_handle_replace(
         &self,
         handle_value: HandleValue,
diff --git a/zircon-syscall/src/hypervisor.rs b/zircon-syscall/src/hypervisor.rs
index 597cbbbb..e12e4d68 100644
--- a/zircon-syscall/src/hypervisor.rs
+++ b/zircon-syscall/src/hypervisor.rs
@@ -10,8 +10,9 @@ use {
 };
 
 impl Syscall<'_> {
-    /// Creates a guest, which is a virtual machine that can be run within the hypervisor,   
-    /// with ```vmar_handle``` used to represent the physical address space of the guest.
+    /// Creates a guest virtual machine.  
+    ///
+    /// The guest is a virtual machine that can be run within the hypervisor, with `vmar_handle` used to represent the physical address space of the guest.
     pub fn sys_guest_create(
         &self,
         resource: HandleValue,
@@ -51,7 +52,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Sets a trap within a guest.  
+    /// Set a trap within a guest.  
     pub fn sys_guest_set_trap(
         &self,
         handle: HandleValue,
@@ -78,7 +79,9 @@ impl Syscall<'_> {
         guest.set_trap(kind, addr as usize, size as usize, port, key)
     }
 
-    /// Creates a VCPU within a guest, which allows for execution within the virtual machine.
+    /// Create a VCPU within a guest.  
+    ///
+    /// The VCPU allows for execution within the virtual machine.
     pub fn sys_vcpu_create(
         &self,
         guest_handle: HandleValue,
@@ -101,7 +104,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Resume execution of a VCPU.
+    /// Resume execution of a VCPU.  
     pub fn sys_vcpu_resume(
         &self,
         handle: HandleValue,
@@ -118,7 +121,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Raise an interrupt on a VCPU and may be called from any thread.
+    /// Raise an interrupt on a VCPU and may be called from any thread.  
     pub fn sys_vcpu_interrupt(&self, handle: HandleValue, vector: u32) -> ZxResult {
         info!(
             "hypervisor.vcpu_interrupt: handle={:#x?}, vector={:?}",
@@ -130,7 +133,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Read the state of a VCPU.
+    /// Read the state of a VCPU.  
     pub fn sys_vcpu_read_state(
         &self,
         handle: HandleValue,
@@ -156,6 +159,7 @@ impl Syscall<'_> {
     }
 
     /// Write the state of a VCPU.  
+    ///
     /// > It is only valid to write the state of handle when execution has been paused.
     pub fn sys_vcpu_write_state(
         &self,
diff --git a/zircon-syscall/src/object.rs b/zircon-syscall/src/object.rs
index a77da671..8e8f4be8 100644
--- a/zircon-syscall/src/object.rs
+++ b/zircon-syscall/src/object.rs
@@ -8,9 +8,10 @@ use {
 
 impl Syscall<'_> {
     /// Ask for various properties of various kernel objects.  
-    /// handle_value: HandleValue, indicates the target kernel object.  
-    /// property: u32, indicates which property to get/set.  
-    /// buffer: usize, holds the property value, and must be a pointer to a buffer of value_size bytes.
+    ///
+    /// `handle_value: HandleValue`, indicates the target kernel object.  
+    /// `property: u32`, indicates which property to get/set.  
+    /// `buffer: usize`, holds the property value, and must be a pointer to a buffer of value_size bytes.  
     pub fn sys_object_get_property(
         &self,
         handle_value: HandleValue,
@@ -108,7 +109,7 @@ impl Syscall<'_> {
         }
     }
 
-    /// Set various properties of various kernel objects.
+    /// Set various properties of various kernel objects.  
     pub fn sys_object_set_property(
         &mut self,
         handle_value: HandleValue,
@@ -187,7 +188,7 @@ impl Syscall<'_> {
         }
     }
 
-    /// A blocking syscall waits for signals on an object
+    /// A blocking syscall waits for signals on an object.
     pub async fn sys_object_wait_one(
         &self,
         handle: HandleValue,
@@ -224,8 +225,9 @@ impl Syscall<'_> {
     }
 
     /// Query information about an object.  
-    /// topic: u32, indicates what specific information is desired.  
-    /// buffer: usize, a pointer to a buffer of size buffer_size to return the information.
+    ///
+    /// `topic: u32`, indicates what specific information is desired.  
+    /// `buffer: usize`, a pointer to a buffer of size buffer_size to return the information.
     pub fn sys_object_get_info(
         &self,
         handle: HandleValue,
@@ -362,7 +364,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Asserts and deasserts the userspace-accessible signal bits on the object's peer.
+    /// Asserts and deasserts the userspace-accessible signal bits on the object's peer.  
     pub fn sys_object_signal_peer(
         &self,
         handle_value: HandleValue,
@@ -382,7 +384,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// A non-blocking syscall subscribes for signals on an object.
+    /// A non-blocking syscall subscribes for signals on an object.  
     pub fn sys_object_wait_async(
         &self,
         handle_value: HandleValue,
@@ -408,6 +410,7 @@ impl Syscall<'_> {
     }
 
     /// Signal an object.  
+    ///
     /// Asserts and deasserts the userspace-accessible signal bits on an object.
     pub fn sys_object_signal(
         &self,
@@ -429,7 +432,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Wait for signals on multiple objects.
+    /// Wait for signals on multiple objects.  
     pub async fn sys_object_wait_many(
         &self,
         mut user_items: UserInOutPtr<UserWaitItem>,
@@ -459,8 +462,9 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Given a kernel object with children objects,   
-    /// obtain a handle to the child specified by the provided kernel object id.
+    /// Find the child of an object by its kid.  
+    ///
+    /// Given a kernel object with children objects, obtain a handle to the child specified by the provided kernel object id.
     pub fn sys_object_get_child(
         &self,
         handle: HandleValue,
diff --git a/zircon-syscall/src/port.rs b/zircon-syscall/src/port.rs
index c93219d1..e49fc19d 100644
--- a/zircon-syscall/src/port.rs
+++ b/zircon-syscall/src/port.rs
@@ -4,7 +4,7 @@ use {
 };
 
 impl Syscall<'_> {
-    /// Create an IO port.
+    /// Create an IO port.  
     pub fn sys_port_create(&self, options: u32, mut out: UserOutPtr<HandleValue>) -> ZxResult {
         info!("port.create: options={:#x}", options);
         let port_handle = Handle::new(Port::new(options), Rights::DEFAULT_PORT);
@@ -13,7 +13,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Wait for a packet arrival in a port.
+    /// Wait for a packet arrival in a port.  
     pub async fn sys_port_wait(
         &self,
         handle_value: HandleValue,
@@ -37,7 +37,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Queue a packet to a port.
+    /// Queue a packet to a port.  
     pub fn sys_port_queue(
         &self,
         handle_value: HandleValue,
diff --git a/zircon-syscall/src/resource.rs b/zircon-syscall/src/resource.rs
index 651fefd9..9d4de032 100644
--- a/zircon-syscall/src/resource.rs
+++ b/zircon-syscall/src/resource.rs
@@ -2,7 +2,7 @@ use {super::*, core::convert::TryFrom, zircon_object::dev::*};
 
 impl Syscall<'_> {
     #[allow(clippy::too_many_arguments)]
-    /// Create a resource object for use with other DDK syscalls.
+    /// Create a resource object for use with other DDK syscalls.  
     pub fn sys_resource_create(
         &self,
         parent_rsrc: HandleValue,
diff --git a/zircon-syscall/src/signal.rs b/zircon-syscall/src/signal.rs
index 72a2f2cb..fcf8aecc 100644
--- a/zircon-syscall/src/signal.rs
+++ b/zircon-syscall/src/signal.rs
@@ -6,7 +6,8 @@ use {
 
 impl Syscall<'_> {
     /// Create a timer.  
-    /// This is an object that can signal when a specified point in time has been reached
+    ///   
+    /// The timer is an object that can signal when a specified point in time has been reached.
     pub fn sys_timer_create(
         &self,
         options: u32,
@@ -33,7 +34,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Create an event.
+    /// Create an event.  
     pub fn sys_event_create(&self, options: u32, mut out: UserOutPtr<HandleValue>) -> ZxResult {
         info!("event.create: options={:#x}", options);
         if options != 0 {
@@ -46,7 +47,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Create an event pair.
+    /// Create an event pair.  
     pub fn sys_eventpair_create(
         &self,
         options: u32,
@@ -68,6 +69,7 @@ impl Syscall<'_> {
     }
 
     /// Start a timer.  
+    ///   
     /// To fire the timer immediately pass a deadline less than or equal to 0.  
     /// The slack parameter specifies a range from deadline - slack to deadline + slack during which the timer is allowed to fire.
     pub fn sys_timer_set(&self, handle: HandleValue, deadline: Deadline, slack: i64) -> ZxResult {
@@ -84,7 +86,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Cancel a timer.
+    /// Cancel a timer.  
     pub fn sys_timer_cancel(&self, handle: HandleValue) -> ZxResult {
         info!("timer.cancel: handle={:#x}", handle);
         let proc = self.thread.proc();
diff --git a/zircon-syscall/src/socket.rs b/zircon-syscall/src/socket.rs
index 639cada2..dcca639c 100644
--- a/zircon-syscall/src/socket.rs
+++ b/zircon-syscall/src/socket.rs
@@ -1,8 +1,9 @@
 use {super::*, zircon_object::ipc::Socket, zircon_object::ipc::SocketFlags};
 
 impl Syscall<'_> {
-    /// Create a socket.  
-    /// Socket, a connected pair of bidirectional stream transports, that can move only data, and that have a maximum capacity.
+    /// Create a socket.   
+    ///   
+    /// Socket is a connected pair of bidirectional stream transports, that can move only data, and that have a maximum capacity.
     pub fn sys_socket_create(
         &self,
         options: u32,
@@ -20,7 +21,8 @@ impl Syscall<'_> {
     }
 
     /// Write data to a socket.  
-    /// Attempts to write ```count: usize``` bytes to the socket specified by ```handle_value```.
+    ///  
+    /// Attempts to write `count: usize` bytes to the socket specified by `handle_value`.  
     pub fn sys_socket_write(
         &self,
         handle_value: HandleValue,
@@ -48,7 +50,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Read data from a socket.
+    /// Read data from a socket.  
     pub fn sys_socket_read(
         &self,
         handle_value: HandleValue,
@@ -77,7 +79,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Prevent future reading or writing on a socket
+    /// Prevent future reading or writing on a socket.   
     pub fn sys_socket_shutdown(&self, socket: HandleValue, options: u32) -> ZxResult {
         let options = SocketFlags::from_bits_truncate(options);
         info!(
diff --git a/zircon-syscall/src/stream.rs b/zircon-syscall/src/stream.rs
index 20cc2e0c..9f261b0c 100644
--- a/zircon-syscall/src/stream.rs
+++ b/zircon-syscall/src/stream.rs
@@ -1,8 +1,9 @@
 use {super::*, bitflags::bitflags, zircon_object::vm::*};
 
 impl Syscall<'_> {
-    /// Create a stream from a VMO.   
-    /// For reads and writes the data in an underlying VMO.
+    /// Create a stream from a VMO.    
+    ///   
+    /// Stream for reads and writes the data in an underlying VMO.  
     pub fn sys_stream_create(
         &self,
         options: u32,
@@ -40,7 +41,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Write data to a stream at the current seek offset.
+    /// Write data to a stream at the current seek offset.   
     pub fn sys_stream_writev(
         &self,
         handle_value: HandleValue,
@@ -71,7 +72,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Write data to a stream at the given offset.
+    /// Write data to a stream at the given offset.   
     pub fn sys_stream_writev_at(
         &self,
         handle_value: HandleValue,
@@ -100,7 +101,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Read data from a stream at the current seek offset.
+    /// Read data from a stream at the current seek offset.   
     pub fn sys_stream_readv(
         &self,
         handle_value: HandleValue,
@@ -127,7 +128,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Read data from a stream at the given offset.
+    /// Read data from a stream at the given offset.   
     pub fn sys_stream_readv_at(
         &self,
         handle_value: HandleValue,
@@ -157,7 +158,8 @@ impl Syscall<'_> {
     }
 
     /// Modify the seek offset.  
-    /// Sets the seek offset of the stream to ```offset``` relative to ```whence```.
+    ///   
+    /// Sets the seek offset of the stream to `offset` relative to `whence`.  
     pub fn sys_stream_seek(
         &self,
         handle_value: HandleValue,
diff --git a/zircon-syscall/src/system.rs b/zircon-syscall/src/system.rs
index e279c75e..b47f7a11 100644
--- a/zircon-syscall/src/system.rs
+++ b/zircon-syscall/src/system.rs
@@ -6,8 +6,9 @@ use {
 
 impl Syscall<'_> {
     /// Retrieve a handle to a system event.  
-    /// root_job: HandleValue, must be a handle to the root job of the system.  
-    /// kind: u32, must be one of the following:  
+    ///
+    /// `root_job: HandleValue`, must be a handle to the root job of the system.  
+    /// `kind: u32`, must be one of the following:    
     /// ```rust
     ///     const EVENT_OUT_OF_MEMORY: u32 = 1;
     ///     const EVENT_MEMORY_PRESSURE_CRITICAL: u32 = 2;
diff --git a/zircon-syscall/src/task.rs b/zircon-syscall/src/task.rs
index 1dffa85b..75c58bf5 100644
--- a/zircon-syscall/src/task.rs
+++ b/zircon-syscall/src/task.rs
@@ -3,6 +3,7 @@ use {super::*, zircon_object::task::*};
 
 impl Syscall<'_> {
     /// Create a new process.  
+    ///   
     /// Upon success, handles for the new process and the root of its address space are returned.
     pub fn sys_process_create(
         &self,
@@ -34,7 +35,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Exits the currently running process.
+    /// Exits the currently running process.  
     pub fn sys_process_exit(&mut self, code: i64) -> ZxResult {
         info!("proc.exit: code={:?}", code);
         let proc = self.thread.proc();
@@ -44,6 +45,7 @@ impl Syscall<'_> {
     }
 
     /// Creates a thread within the specified process.  
+    ///   
     /// Upon success a handle for the new thread is returned.
     pub fn sys_thread_create(
         &self,
@@ -68,7 +70,8 @@ impl Syscall<'_> {
     }
 
     /// Start execution on a process.  
-    /// This system call is similar to ```zx_thread_start()```, but is used for the purpose of starting the first thread in a process.
+    ///   
+    /// This system call is similar to `zx_thread_start()`, but is used for the purpose of starting the first thread in a process.
     pub fn sys_process_start(
         &self,
         proc_handle: HandleValue,
@@ -101,6 +104,7 @@ impl Syscall<'_> {
     }
 
     /// Write one aspect of thread state.    
+    ///   
     /// The thread state may only be written when the thread is halted for an exception or the thread is suspended.
     pub fn sys_thread_write_state(
         &self,
@@ -122,7 +126,8 @@ impl Syscall<'_> {
     }
 
     /// Sets process as critical to job.   
-    /// When process terminates, job will be terminated as if ```zx_task_kill()``` was called on it.
+    ///   
+    /// When process terminates, job will be terminated as if `zx_task_kill()` was called on it.
     pub fn sys_job_set_critical(
         &self,
         job_handle: HandleValue,
@@ -147,7 +152,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Start execution on a thread.
+    /// Start execution on a thread.  
     pub fn sys_thread_start(
         &self,
         handle_value: HandleValue,
@@ -170,6 +175,7 @@ impl Syscall<'_> {
     }
 
     /// Terminate the current running thread.   
+    ///
     /// Causes the currently running thread to cease running and exit.
     pub fn sys_thread_exit(&mut self) -> ZxResult {
         info!("thread.exit:");
@@ -179,7 +185,8 @@ impl Syscall<'_> {
     }
 
     /// Suspend the given task.   
-    /// > This function replaces task_suspend. When all callers are updated, ```zx_task_suspend()``` will be deleted and this function will be renamed ```zx_task_suspend()```.
+    ///
+    /// > This function replaces task_suspend. When all callers are updated, `zx_task_suspend()` will be deleted and this function will be renamed ```zx_task_suspend()```.
     pub fn sys_task_suspend_token(
         &self,
         handle: HandleValue,
@@ -241,7 +248,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// creates a new child job object given a parent job.
+    /// Create a new child job object given a parent job.  
     pub fn sys_job_create(
         &self,
         parent: HandleValue,
@@ -265,7 +272,7 @@ impl Syscall<'_> {
         }
     }
 
-    /// Sets one or more security and/or resource policies to an empty job.
+    /// Sets one or more security and/or resource policies to an empty job.  
     pub fn sys_job_set_policy(
         &self,
         handle: HandleValue,
@@ -306,7 +313,8 @@ impl Syscall<'_> {
         }
     }
 
-    /// Read from the given process's address space.
+    /// Read from the given process's address space.  
+    ///   
     /// > This function will eventually be replaced with something vmo-centric.
     pub fn sys_process_read_memory(
         &self,
@@ -329,7 +337,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Write into the given process's address space.
+    /// Write into the given process's address space.  
     pub fn sys_process_write_memory(
         &self,
         handle_value: HandleValue,
diff --git a/zircon-syscall/src/time.rs b/zircon-syscall/src/time.rs
index 337ba7b2..51643570 100644
--- a/zircon-syscall/src/time.rs
+++ b/zircon-syscall/src/time.rs
@@ -16,7 +16,7 @@ const ZX_CLOCK_UTC: u32 = 1;
 const ZX_CLOCK_THREAD: u32 = 2;
 
 impl Syscall<'_> {
-    /// Create a new clock object.
+    /// Create a new clock object.  
     pub fn sys_clock_create(
         &self,
         _options: u64,
@@ -27,9 +27,10 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Acquire the current time.
-    /// Returns the current time of clock_id via ```time```.
-    /// Returns whether ```clock_id``` was valid.
+    /// Acquire the current time.  
+    ///   
+    /// + Returns the current time of clock_id via `time`.  
+    /// + Returns whether `clock_id` was valid.  
     pub fn sys_clock_get(&self, clock_id: u32, mut time: UserOutPtr<u64>) -> ZxResult {
         info!("clock.get: id={}", clock_id);
         match clock_id {
@@ -49,7 +50,7 @@ impl Syscall<'_> {
         }
     }
 
-    /// Perform a basic read of the clock.
+    /// Perform a basic read of the clock.  
     pub fn sys_clock_read(&self, handle: HandleValue, mut now: UserOutPtr<u64>) -> ZxResult {
         info!("clock.read: handle={:#x?}", handle);
         warn!("ignore clock handle");
@@ -87,8 +88,9 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// High resolution sleep.  
-    /// A ```deadline``` value less than or equal to 0 immediately yields the thread.
+    /// Sleep for some number of nanoseconds.
+    ///   
+    /// A `deadline` value less than or equal to 0 immediately yields the thread.
     pub async fn sys_nanosleep(&self, deadline: Deadline) -> ZxResult {
         info!("nanosleep: deadline={:?}", deadline);
         if deadline.0 <= 0 {
diff --git a/zircon-syscall/src/vmar.rs b/zircon-syscall/src/vmar.rs
index 9b11a4dd..0c7993bb 100644
--- a/zircon-syscall/src/vmar.rs
+++ b/zircon-syscall/src/vmar.rs
@@ -14,7 +14,8 @@ fn amount_of_alignments(options: u32) -> ZxResult<usize> {
 
 impl Syscall<'_> {
     /// Allocate a new subregion.  
-    /// Creates a new VMAR within the one specified by ```parent_vmar```.
+    ///   
+    /// Creates a new VMAR within the one specified by `parent_vmar`.  
     pub fn sys_vmar_allocate(
         &self,
         parent_vmar: HandleValue,
@@ -75,7 +76,8 @@ impl Syscall<'_> {
     }
 
     #[allow(clippy::too_many_arguments)]
-    /// Add a memory mapping.  
+    /// Add a memory mapping.   
+    ///   
     /// Maps the given VMO into the given virtual memory address region.
     pub fn sys_vmar_map(
         &self,
@@ -162,8 +164,9 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Destroy a virtual memory address region.  
-    /// Unmaps all mappings within the given region, and destroys all sub-regions of the region.  
+    /// Destroy a virtual memory address region.   
+    ///   
+    /// Unmaps all mappings within the given region, and destroys all sub-regions of the region.   
     /// > This operation is logically recursive.
     pub fn sys_vmar_destroy(&self, handle_value: HandleValue) -> ZxResult {
         info!("vmar.destroy: handle={:?}", handle_value);
@@ -173,7 +176,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Set protection of virtual memory pages.
+    /// Set protection of virtual memory pages.  
     pub fn sys_vmar_protect(
         &self,
         handle_value: HandleValue,
@@ -202,7 +205,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Unmap virtual memory pages.
+    /// Unmap virtual memory pages.  
     pub fn sys_vmar_unmap(&self, handle_value: HandleValue, addr: usize, len: usize) -> ZxResult {
         info!(
             "vmar.unmap: handle_value={:#x}, addr={:#x}, len={:#x}",
diff --git a/zircon-syscall/src/vmo.rs b/zircon-syscall/src/vmo.rs
index 7c2ea5e7..11017e99 100644
--- a/zircon-syscall/src/vmo.rs
+++ b/zircon-syscall/src/vmo.rs
@@ -7,7 +7,7 @@ use {
 };
 
 impl Syscall<'_> {
-    /// Create a virtual memory object(VMO).
+    /// Create a new virtual memory object(VMO).  
     pub fn sys_vmo_create(
         &self,
         size: u64,
@@ -29,7 +29,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Read bytes from the VMO.
+    /// Read bytes from a VMO.  
     pub fn sys_vmo_read(
         &self,
         handle_value: HandleValue,
@@ -54,7 +54,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Write bytes to the VMO.
+    /// Write bytes to a VMO.  
     pub fn sys_vmo_write(
         &self,
         handle_value: HandleValue,
@@ -75,7 +75,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Add execute rights to a VMO.
+    /// Add execute rights to a VMO.  
     pub fn sys_vmo_replace_as_executable(
         &self,
         handle: HandleValue,
@@ -102,7 +102,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Read the current size of a VMO object.
+    /// Obtain the current size of a VMO object.  
     pub fn sys_vmo_get_size(&self, handle: HandleValue, mut size: UserOutPtr<usize>) -> ZxResult {
         info!("vmo.get_size: handle={:?}", handle);
         let proc = self.thread.proc();
@@ -111,7 +111,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Create a new virtual memory object (VMO) a child of an existing vmo.
+    /// Create a child of an existing VMO (new virtual memory object).  
     pub fn sys_vmo_create_child(
         &self,
         handle_value: HandleValue,
@@ -175,7 +175,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Create a VM object referring to a specific contiguous range of physical memory.
+    /// Create a VM object referring to a specific contiguous range of physical memory.  
     pub fn sys_vmo_create_physical(
         &self,
         resource: HandleValue,
@@ -204,7 +204,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Create a VM object referring to a specific contiguous range of physical frame.
+    /// Create a VM object referring to a specific contiguous range of physical frame.  
     pub fn sys_vmo_create_contiguous(
         &self,
         bti: HandleValue,
@@ -236,7 +236,7 @@ impl Syscall<'_> {
         Ok(())
     }
 
-    /// Resize a VMO object.
+    /// Resize a VMO object.  
     pub fn sys_vmo_set_size(&self, handle_value: HandleValue, size: usize) -> ZxResult {
         let proc = self.thread.proc();
         let vmo = proc.get_object_with_rights::<VmObject>(handle_value, Rights::WRITE)?;
@@ -249,7 +249,9 @@ impl Syscall<'_> {
         vmo.set_len(size)
     }
 
-    /// Perform an operation on a range of a VMO.performs cache and memory operations against pages held by the VMO.
+    /// Perform an operation on a range of a VMO.  
+    ///   
+    /// Performs cache and memory operations against pages held by the VMO.  
     pub fn sys_vmo_op_range(
         &self,
         handle_value: HandleValue,
@@ -296,7 +298,7 @@ impl Syscall<'_> {
         }
     }
 
-    /// Set the caching policy for pages held by a VMO.
+    /// Set the caching policy for pages held by a VMO.  
     pub fn sys_vmo_cache_policy(&self, handle_value: HandleValue, policy: u32) -> ZxResult {
         let proc = self.thread.proc();
         let vmo = proc.get_object_with_rights::<VmObject>(handle_value, Rights::MAP)?;