commentary update. add a minimal example.

src/Graphics/Vty.hs

@@ -1,14 +1,31 @@
 -- | Vty supports input and output to terminal devices.
 --
---  - The input is provides as a sequence of 'Event's.
+--  - Input to the terminal is provided to the app as a sequence of 'Event's.
 --
 --  - The output is defined by a 'Picture'. Which is one or more layers of 'Image's.
---      The constructors in "Graphics.Vty.Image.Internal" should not be used directly. The module
---      "Graphics.Vty.Image" provides a number of constructor equations that will build correct
---      'Image' values. See 'string', '<|>', and '<->' for starters.
+--
+--      - The module "Graphics.Vty.Image" provides a number of constructor equations that will build
+--      correct 'Image' values. See 'string', '<|>', and '<->' for starters.
+--
+--      - The constructors in "Graphics.Vty.Image.Internal" should not be used.
 --
 --  - 'Image's can be styled using 'Attr'. See "Graphics.Vty.Attributes".
 -- 
+-- See the vty-examples package for a number of examples.
+--
+-- @
+--  main = do
+--      vty <- 'mkVty' def
+--      let line0 = 'string' (def `withForeColor` 'green') \"first line\"
+--          line1 = 'string' (def `withBackColor` 'blue') \"second line\"
+--          img = line0 '<->' line1
+--          pic = 'picForImage' img
+--      'update' vty pic
+--      e :: 'Event' <- 'nextEvent' vty
+--      'shutdown' vty
+--      print $ \"Last event was: \" ++ show e
+-- @
+-- 
 -- Good sources of documentation for terminal programming are:
 --
 --  - <https://github.com/b4winckler/vim/blob/master/src/term.c>
@@ -24,6 +41,7 @@
 --  - <http://vt100.net/docs/vt100-ug/chapter3.html vt100 control sequences>
 module Graphics.Vty ( Vty(..)
                     , mkVty
+                    , module Graphics.Vty.Config
                     , module Graphics.Vty.Input
                     , module Graphics.Vty.Output
                     , module Graphics.Vty.Picture
@@ -72,22 +90,22 @@ data Vty = Vty
     , inputIface :: Input
       -- | The output interface. See 'Output'
     , outputIface :: Output
-      -- | Refresh the display. Normally the library takes care of refreshing.  Nonetheless, some
-      -- other program might output to the terminal and mess up the display.  In that case the
-      -- application might want to force a refresh.
+      -- | Refresh the display. 'nextEvent' will refresh the display if a resize occurs.
+      -- If other programs output to the terminal and mess up the display then the application might
+      -- want to force a refresh.
     , refresh :: IO ()
       -- | Clean up after vty.
       -- The above methods will throw an exception if executed after this is executed.
     , shutdown :: IO () 
     }
 
 -- | Set up the state object for using vty.  At most one state object should be
--- created at a time.
+-- created at a time for a given terminal device.
 --
 -- The specified config is added to the 'userConfig'. With the 'userConfig' taking precedence.
 -- See "Graphics.Vty.Config"
 --
--- For most applications `mkVty def` is sufficient.
+-- For most applications @mkVty def@ is sufficient.
 mkVty :: Config -> IO Vty
 mkVty appConfig = do
     config <- mappend <$> pure appConfig <*> userConfig

src/Graphics/Vty/Config.hs

@@ -1,35 +1,36 @@
 {-# LANGUAGE FlexibleContexts #-}
 {-# LANGUAGE NoMonomorphismRestriction #-}
--- | A 'Config' can be provided to mkVty to customize the applications use of vty.
+-- | A 'Config' can be provided to mkVty to customize the applications use of vty. A config file can
+-- be used to customize vty for a user's system.
 --
--- The 'Config' provided is mappend'd to 'Config's loaded from 'getAppUserDataDirectory'`/config`
--- and $VTY_CONFIG_FILE. The $VTY_CONFIG_FILE takes precedence over the `config` file or the
+-- The 'Config' provided is mappend'd to 'Config's loaded from @'getAppUserDataDirectory'/config@
+-- and @$VTY_CONFIG_FILE@. The @$VTY_CONFIG_FILE@ takes precedence over the @config@ file or the
 -- application provided 'Config'.
--- 
+--
 -- Each line of the input config is processed individually. Lines that fail to parse are ignored.
 -- Later entries take precedence over earlier.
 --
--- * Classify Table Overrides - "map"
+-- * Classify Table Overrides - @map@
 --
 -- Directive format:
 --
 -- @
---  entry := "map" string key modifier_list
+--  entry := \"map\" string key modifier_list
 --  key := KEsc | KChar Char | KBS ... (same as 'Key')
---  modifier_list := "[" modifier+ "]"
+--  modifier_list := \"[\" modifier+ \"]\"
 --  modifier := MShift | MCtrl | MMeta | MAlt
---  string := "\"" chars+ "\""
+--  string := \"\\\"\" chars+ \"\\\"\"
 -- @
 --
--- EG: If the contents of input.conf are
+-- EG: If the contents are
 --
 -- @
---  map "\ESC[B" KUp []
---  map "\ESC[1;3B" KDown [MAlt]
+--  map \"\\ESC[B\" KUp []
+--  map \"\\ESC[1;3B\" KDown [MAlt]
 -- @
 --
--- Then the bytes "\ESC[B" will result in the KUp event. The bytes "\ESC[1;3B" will result in the
--- event KDown with the MAlt modifier.
+-- Then the bytes @\"\\ESC[B\"@ will result in the KUp event. The bytes @\"\\ESC[1;3B\"@ will result
+-- in the event KDown with the MAlt modifier.
 --
 module Graphics.Vty.Config where
 
@@ -82,6 +83,7 @@ instance Monoid Config where
 
 type ConfigParser s a = ParsecT s () (Writer Config) a
 
+-- | Config from @'getAppUserDataDirectory'/config@ and @$VTY_CONFIG_FILE@
 userConfig :: IO Config
 userConfig = do
     vtyConfig <- (mappend <$> getAppUserDataDirectory "vty" <*> pure "/config") >>= parseConfigFile
@@ -124,6 +126,8 @@ parseOverride = do
     modifiers <- parseModifiers
     lift $ tell $ def { inputOverrides = [(bytes, EvKey key modifiers)] }
 
+-- TODO: Generated by a vim macro. There is a better way here. Derive parser? Use Read
+-- instance?
 parseKey = do
     key <- P.identifier configLexer
     case key of
@@ -167,8 +171,6 @@ parseModifier = do
 
 ignoreLine = void $ manyTill anyChar newline
 
--- TODO: Generated by a vim macro. There is a better way here. Derive parser? Use Read
--- instance?
 parseConfig = void $ many $ do
     P.whiteSpace configLexer
     let directives = [parseOverride]

test/MinimalExample.hs

@@ -0,0 +1,16 @@
+module Main where
+
+import Graphics.Vty
+
+import Data.Default
+
+main = do
+    vty <- mkVty def
+    let line0 = string (def `withForeColor` green) "first line"
+        line1 = string (def `withBackColor` blue) "second line"
+        img = line0 <-> line1
+        pic = picForImage img
+    update vty pic
+    e <- nextEvent vty
+    shutdown vty
+    print $ "Last event was: " ++ show e