haddock improvemnts

Propellor.hs

@@ -1,11 +1,44 @@
--- | Pulls in lots of useful modules for building Properties.
+-- | Pulls in lots of useful modules for building and using Properties.
+--
+-- Propellor enures that the system it's run in satisfies a list of
+-- properties, taking action as necessary when a property is not yet met.
+--
+-- A simple propellor program example:
+--
+--
+--> import Propellor
+--> import Propellor.CmdLine
+--> import qualified Propellor.Property.File as File
+--> import qualified Propellor.Property.Apt as Apt
+--> 
+--> main :: IO ()
+--> main = defaultMain getProperties
+--> 
+--> getProperties :: HostName -> Maybe [Property]
+--> getProperties "example.com" = Just
+-->    [ Apt.installed ["mydaemon"]
+-->    , "/etc/mydaemon.conf" `File.containsLine` "secure=1"
+-->        `onChange` cmdProperty "service" ["mydaemon", "restart"]]
+-->    ]
+--> getProperties _ = Nothing
+--
+-- See config.hs for a more complete example, and clone Propellor's
+-- git repository for a deployable system using Propellor:
+-- git clone <git://git.kitenet.net/propellor>
 
-module Propellor (module X) where
+module Propellor (
+	  module Propellor.Types
+	, module Propellor.Property
+	, module Propellor.Property.Cmd
+	, module Propellor.PrivData
 
-import Propellor.Types as X
+	, module X
-import Propellor.Property as X
+) where
-import Propellor.Property.Cmd as X
+
-import Propellor.PrivData as X
+import Propellor.Types
+import Propellor.Property
+import Propellor.Property.Cmd
+import Propellor.PrivData
 
 import Utility.PartialPrelude as X
 import Utility.Process as X

Propellor/PrivData.hs

@@ -18,9 +18,9 @@ import Utility.Tmp
 import Utility.SafeCommand
 import Utility.Misc
 
-{- | Note that removing or changing field names will break the
+-- | Note that removing or changing field names will break the
- - serialized privdata files, so don't do that!
+-- serialized privdata files, so don't do that!
- - It's fine to add new fields. -}
+-- It's fine to add new fields.
 data PrivDataField
 	= DockerAuthentication
 	| SshPrivKey UserName

Propellor/Property/File.hs

@@ -4,12 +4,12 @@ import Propellor
 
 type Line = String
 
-{- | Replaces all the content of a file. -}
+-- | Replaces all the content of a file.
 hasContent :: FilePath -> [Line] -> Property
 f `hasContent` newcontent = fileProperty ("replace " ++ f)
 	(\_oldcontent -> newcontent) f
 
-{- | Ensures that a line is present in a file, adding it to the end if not. -}
+-- | Ensures that a line is present in a file, adding it to the end if not.
 containsLine :: FilePath -> Line -> Property
 f `containsLine` l = fileProperty (f ++ " contains:" ++ l) go f
   where
@@ -17,13 +17,13 @@ f `containsLine` l = fileProperty (f ++ " contains:" ++ l) go f
 		| l `elem` ls = ls
 		| otherwise = ls++[l]
 
-{- | Ensures that a line is not present in a file.
+-- | Ensures that a line is not present in a file.
- - Note that the file is ensured to exist, so if it doesn't, an empty
+-- Note that the file is ensured to exist, so if it doesn't, an empty
- - file will be written. -}
+-- file will be written. -}
 lacksLine :: FilePath -> Line -> Property
 f `lacksLine` l = fileProperty (f ++ " remove: " ++ l) (filter (/= l)) f
 
-{- | Removes a file. Does not remove symlinks or non-plain-files. -}
+-- | Removes a file. Does not remove symlinks or non-plain-files.
 notPresent :: FilePath -> Property
 notPresent f = check (doesFileExist f) $ Property (f ++ " not present") $ 
 	makeChange $ nukeFile f