From 7a9aac48f2fce05bd6fd8daf9cb3a52098a841eb Mon Sep 17 00:00:00 2001
From: tv <tv@shackspace.de>
Date: Mon, 3 Nov 2014 19:59:44 +0000
Subject: Reduce redundancy in CGroup documentation.

---
 CGroup.hs       |  6 +++---
 CGroup/Types.hs | 22 +++++++++++-----------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/CGroup.hs b/CGroup.hs
index 399ec84..11b54cd 100644
--- a/CGroup.hs
+++ b/CGroup.hs
@@ -25,19 +25,19 @@ import System.IO.Streams.Attoparsec (parseFromStream)
 import System.IO.Streams.File (withFileAsInput)
 
 
--- | @'createCGroup' g@ creates a new cgroup @g@.
+-- | Create a new cgroup.
 createCGroup :: CGroup -> IO ()
 createCGroup =
     createDirectory . cgroupPath
 
 
--- | @'classifyTask' g pid@ places task @pid@ into cgroup @g@.
+-- | Places a task into a cgroup.
 classifyTask :: ProcessID -> CGroup -> IO ()
 classifyTask pid g =
     writeFile (tasksFile g) (show pid)
 
 
--- | @'listTasks' g@ returns tasks of cgroup @g@.
+-- | Retrieve the tasks of a cgroup.
 listTasks :: CGroup -> IO (Set ProcessID)
 listTasks g =
     withFileAsInput (tasksFile g) $ parseFromStream tasksParser
diff --git a/CGroup/Types.hs b/CGroup/Types.hs
index 53ff4fa..98422f3 100644
--- a/CGroup/Types.hs
+++ b/CGroup/Types.hs
@@ -6,9 +6,12 @@
 --
 
 module CGroup.Types
-    ( CGroup
+    (
+    -- * CGroup
+      CGroup
     , cgroup
     , cgroupPath
+    -- * Other types
     , ProcessID
     ) where
 
@@ -16,18 +19,16 @@ import Data.Monoid
 import qualified System.FilePath as FP
 
 
--- | A 'CGroup' is defined by a mount point and a cgroup name.
---
--- The mount point specifies where the cgroup hierarchy is mounted.
--- The cgroup name is a 'FilePath' relative to the mount point.
+-- | A 'CGroup' is defined by two 'FilePath's, a mount point and a cgroup
+-- name.  The mount point specifies where the cgroup hierarchy is mounted.
+-- The cgroup name is a directory, relative to the mount point.
 data CGroup = CGroup { mountPoint, cgroupName :: FilePath }
   deriving Show
 
 
--- | @'cgroup' mountPoint cgroupName@ is a smart constructor for 'CGroup'.
---
--- It will return 'Nothing' if @cgroupName@ could point outside
--- @mountPoint@ in order to prevent directory traversal attacks.
+-- | Smart constructor. Takes a mount point and a cgroup name.
+-- It will return 'Nothing' if the cgroup could point outside the mount point,
+-- i.e. if the cgroup name is an absolute path, or contains @".."@.
 cgroup :: FilePath -> FilePath -> Maybe CGroup
 cgroup mp0 cgn0
     | ".." `elem` parts = Nothing
@@ -41,11 +42,10 @@ cgroup mp0 cgn0
     normaliseCGroupName = FP.dropTrailingPathSeparator . FP.normalise
 
 
--- | @'cgroupPath' g@ returns the absolute 'FilePath' of cgroup @g@.
+-- | Path of a cgroup's tasks file.
 cgroupPath :: CGroup -> FilePath
 cgroupPath CGroup { mountPoint = mp, cgroupName = cgn } =
     mp <> cgn
 
 
--- | A 'ProcessID' defines a task / process.
 type ProcessID = Int
-- 
cgit v1.2.3