Refactor documentation a little

Author: marmistrz

src/sys/ptrace.rs

@@ -3,8 +3,6 @@ use {Errno, Error, Result};
 use libc::{c_void, c_long, siginfo_t};
 use ::unistd::Pid;
 
-//------------------ First part: a low-level wrapper for ptrace -----------------//
-
 #[cfg(all(target_os = "linux",
           any(target_arch = "x86",
               target_arch = "x86_64",
@@ -79,6 +77,7 @@ mod ffi {
 /// Performs a `ptrace` request. If the request in question is provided by a specialised function
 /// this function will return an unsupported operation error.
 ///
+/// # Safety
 /// When used incorrectly, this function may crash the tracer or the tracee, thus is marked `unsafe`.
 pub unsafe fn ptrace(request: ptrace::PtraceRequest, pid: Pid, addr: *mut c_void, data: *mut c_void) -> Result<c_long> {
     use self::ptrace::*;
@@ -151,11 +150,8 @@ pub fn ptrace_setsiginfo(pid: Pid, sig: &siginfo_t) -> Result<()> {
     }
 }
 
-//-------------------------- Second part: a high-level wrapper for ptrace ----------------------//
-
 #[cfg(target_arch = "x86_64")]
 // We're going to export it anyway
-#[allow(dead_code)]
 #[allow(non_camel_case_types)]
 pub enum Register {
     R15 = 0 * 8,
@@ -202,10 +198,11 @@ pub fn peekuser(pid: Pid, reg: Register) -> Result<Word> {
     unsafe {
         ptrace(ptrace::PTRACE_PEEKUSER, pid, reg_arg, ptr::null_mut()).map(|r| r as Word)
     }
-} 
+}
 
 /// Makes the `PTRACE_POKEUSER` request to ptrace
-/// 
+///
+/// # Safety
 /// When incorrectly used, may change the registers to bad values,
 /// causing e.g. memory being corrupted by a syscall, thus is marked unsafe
 pub unsafe fn pokeuser(pid: Pid, reg: Register, val: Word) -> Result<()> {
@@ -226,17 +223,19 @@ pub fn traceme() -> Result<()> {
 }
 
 /// Makes the `PTRACE_PEEKDATA` request to ptrace
-/// 
+///
+/// # Safety
 /// This function allows to access arbitrary data in the traced process
 /// and may crash the inferior if used incorrectly and is thus marked `unsafe`.
 pub unsafe fn peekdata(pid: Pid, addr: usize) -> Result<Word> {
     ptrace(ptrace::PTRACE_PEEKDATA, pid, addr as *mut c_void, ptr::null_mut()).map(|r| r as Word)
 }
 
-/// Makes the `PTRACE_PEEKDATA` request to ptrace
+/// Makes the `PTRACE_POKEDATA` request to ptrace
 ///
+/// # Safety
 /// This function allows to access arbitrary data in the traced process
-/// and may crash the inferior or introduce race conditions if used 
+/// and may crash the inferior or introduce race conditions if used
 /// incorrectly and is thus marked `unsafe`.
 pub unsafe fn pokedata(pid: Pid, addr: usize, val: Word) -> Result<()> {
     ptrace(