More docs!

Signed-off-by: Levente Kurusa <lkurusa@acm.org>

src/cgroup.rs

@@ -50,10 +50,17 @@ impl Cgroup {
         cg
     }
 
+    /// The list of subsystems that this control group supports.
     pub fn subsystems(self: &Self) -> &Vec<Subsystem> {
         &self.subsystems
     }
 
+    /// Deletes the control group.
+    ///
+    /// Note that this function makes no effort in cleaning up the descendant and the underlying
+    /// system call will fail if there are any descendants. Thus, one should check whether it was
+    /// actually removed, and remove the descendants first if not. In the future, this behavior
+    /// will change.
     pub fn delete(self: Self) {
         self.subsystems.into_iter().for_each(|sub| {
             match sub {
@@ -74,12 +81,23 @@ impl Cgroup {
         });
     }
 
+    /// Apply a set of resource limits to the control group.
     pub fn apply(self: &Self, res: &Resources) {
         for subsystem in &self.subsystems {
             subsystem.to_controller().apply(res);
         }
     }
 
+    /// Retrieve a container based on type inference.
+    ///
+    /// ## Example:
+    ///
+    /// ```
+    /// let pids: &PidController = control_group.controller_of()
+    ///                             .expect("No pids controller attached!");
+    /// let cpu: &CpuController = control_group.controller_of()
+    ///                             .expect("No cpu controller attached!");
+    /// ```
     pub fn controller_of<'a, T>(self: &'a Self) -> Option<&'a T>
         where &'a T: From<&'a Subsystem>,
                   T: Controller + ControllIdentifier,
@@ -96,6 +114,7 @@ impl Cgroup {
         None
     }
 
+    /// Attach a task to the control group.
     pub fn add_task(self: &Self, pid: CgroupPid) {
         self.subsystems().iter().for_each(|sub| sub.to_controller().add_task(&pid));
     }

src/hierarchies.rs

@@ -1,3 +1,8 @@
+//! This module represents the various control group hierarchies the Linux kernel supports.
+//!
+//! Currently, we only support the cgroupv1 hierarchy, but in the future we will add support for
+//! the Unified Hierarchy.
+
 use std::io::BufRead;
 use std::io::BufReader;
 use std::fs::File;
@@ -18,6 +23,8 @@ use ::net_prio::NetPrioController;
 use ::hugetlb::HugeTlbController;
 use ::rdma::RdmaController;
 
+
+/// The standard, original cgroup implementation. Often referred to as "cgroupv1".
 pub struct V1 {
     mount_point: String,
 }
@@ -83,17 +90,11 @@ impl Hierarchy for V1 {
     fn root(self: &Self) -> PathBuf {
         PathBuf::from(self.mount_point.clone())
     }
-
-    fn can_create_cgroup(self: &Self) -> bool {
-        /*
-         * V1 hierarchies do not support creating cgroups,
-         * they have to be created in a subsystem
-         */
-        false
-    }
 }
 
 impl V1 {
+    /// Finds where control groups are mounted to and returns a hierarchy in which control groups
+    /// can be created.
     pub fn new() -> Self {
         let mount_point = find_v1_mount().unwrap();
         V1 {

src/lib.rs

@@ -184,9 +184,13 @@ pub trait ControllIdentifier {
 /// Control group hierarchy (right now, only V1 is supported, but in the future Unified will be
 /// implemented as well).
 pub trait Hierarchy {
+    /// Returns what subsystems are supported by the hierarchy.
     fn subsystems(self: &Self) -> Vec<Subsystem>;
-    fn can_create_cgroup(self: &Self) -> bool;
+    /// Returns the root directory of the hierarchy.
     fn root(self: &Self) -> PathBuf;
+    /// Checks whether a certain subsystem is supported in the hierarchy.
+    ///
+    /// This is an internal function and should not be used.
     fn check_support(self: &Self, sub: Controllers) -> bool;
 }
 
@@ -299,7 +303,10 @@ pub struct Resources {
     pub blkio: BlkIoResources,
 }
 
+/// A structure representing a `pid`. Currently implementations exist for `u64` and
+/// `std::process::Child`.
 pub struct CgroupPid {
+    /// The process identifier
     pub pid: u64,
 }