From 2fb2fcd4141e0171915e4c137d86a218c6e4c69a Mon Sep 17 00:00:00 2001
From: Pascal Bach <pascal.bach@nextrem.ch>
Date: Thu, 9 Aug 2018 23:22:21 +0200
Subject: [PATCH] Improve documentation of kmod functions

---
 src/kmod.rs | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/src/kmod.rs b/src/kmod.rs
index e7ad072138..e853261b14 100644
--- a/src/kmod.rs
+++ b/src/kmod.rs
@@ -1,4 +1,6 @@
 //! Load and unload kernel modules.
+//!
+//! For more details see
 
 use libc;
 use std::ffi::CStr;
@@ -7,14 +9,21 @@ use std::os::unix::io::AsRawFd;
 use errno::Errno;
 use Result;
 
-/// Loads an ELF image into kernel space, performs any necessary symbol relocations,
-/// initializes module parameters to values provided by the caller, and then runs the module's init function.
-/// This function requires privilege.
+/// Loads a kernel module from a buffer.
 ///
-/// The module_image argument points to a buffer containing the binary image to be loaded.
-/// The module image should be a valid ELF image, built for the running kernel.
+/// It loads an ELF image into kernel space,
+/// performs any necessary symbol relocations,
+/// initializes module parameters to values provided by the caller,
+/// and then runs the module's init function.
 ///
-/// The param_values argument is a string containing space-delimited specifications of the values for module parameters.
+/// This function requires `CAP_SYS_MODULE` privilege.
+///
+/// The `module_image` argument points to a buffer containing the binary image
+/// to be loaded. The buffer should contain a valid ELF image
+/// built for the running kernel.
+///
+/// The `param_values` argument is a string containing space-delimited specifications
+/// of the values for module parameters.
 /// Each of the parameter specifications has the form:
 ///
 /// `name[=value[,value...]]`
@@ -30,9 +39,10 @@ use Result;
 /// let mut f = File::open("mykernel.ko").unwrap();
 /// let mut contents: Vec<u8> = Vec::new();
 /// f.read_to_end(&mut contents).unwrap();
-/// init_module(&mut contents, &CString::new("").unwrap()).unwrap();
+/// init_module(&mut contents, &CString::new("who=Rust when=Now,12").unwrap()).unwrap();
 /// ```
 ///
+/// See [`man init_module(2)`](http://man7.org/linux/man-pages/man2/init_module.2.html) for more information.
 pub fn init_module(module_image: &[u8], param_values: &CStr) -> Result<()> {
     let res = unsafe {
         libc::syscall(
@@ -69,6 +79,7 @@ libc_bitflags!(
 /// finit_module(&f, &CString::new("").unwrap(), ModuleInitFlags::empty()).unwrap();
 /// ```
 ///
+/// See [`man init_module(2)`](http://man7.org/linux/man-pages/man2/init_module.2.html) for more information.
 pub fn finit_module<T: AsRawFd>(fd: &T, param_values: &CStr, flags: ModuleInitFlags) -> Result<()> {
     let res = unsafe {
         libc::syscall(
@@ -84,7 +95,9 @@ pub fn finit_module<T: AsRawFd>(fd: &T, param_values: &CStr, flags: ModuleInitFl
 
 libc_bitflags!(
     /// Flags used by `delete_module`.
-    /// see man delete_module(2) for a detailed description how these flags work.
+    ///
+    /// See [`man delete_module(2)`](http://man7.org/linux/man-pages/man2/delete_module.2.html)
+    /// for a detailed description how these flags work.
     pub struct DeleteModuleFlags: libc::c_int {
         O_NONBLOCK;
         O_TRUNC;
@@ -102,6 +115,7 @@ libc_bitflags!(
 /// delete_module(&CString::new("mymod").unwrap(), DeleteModuleFlags::O_NONBLOCK).unwrap();
 /// ```
 ///
+/// See [`man delete_module(2)`](http://man7.org/linux/man-pages/man2/delete_module.2.html) for more information.
 pub fn delete_module(name: &CStr, flags: DeleteModuleFlags) -> Result<()> {
     let res = unsafe { libc::syscall(libc::SYS_delete_module, name.as_ptr(), flags.bits()) };