Add a little more documentation.

Make 'doc' a phony target.

diff --git a/htsn-common.cabal b/htsn-common.cabal
index e5f6939e49b85dd9a5bea85928005befbf81a9de..06b36b069645d88dfb332fb22fe1a78f04fd5940 100644 (file)
--- a/htsn-common.cabal
+++ b/htsn-common.cabal
@@ -8,7 +8,7 @@ license:        GPL-3
 license-file:   doc/LICENSE
 build-type:     Simple
 synopsis:
-  Library used by both htsn and htsn-import.
+  Display/logging facilities used by both htsn and htsn-import.
 description:
   This library contains three modules,
   .
@@ -20,6 +20,20 @@ description:
   .
   They work together to provide \"reporting\" for the htsn and htsn-import
   executables which both display and log things in the same way.
+  .
+  The Network.Services.TSN.Logging module allows the application to
+  log to syslog, a file, or both. Four convenience functions are
+  provided to log messages at each priority: error, debug, info, and
+  warn.
+  .
+  The Network.Services.TSN.Terminal provides similar functions that
+  instead display messages on the console (terminal). The output is
+  color-coded according to the severity of the message.
+  .
+  The Network.Services.TSN.Report modules contains convenience
+  functions that both log and display informational message. This is
+  what an (optionally interactive) application will usually want to
+  do.
 
 library
   hs-source-dirs: src/

diff --git a/makefile b/makefile
index 5f49b4b098a298a196008d1da644daa9ba545704..556200d4dd5947eef49e844fe5eeabbd2e40e748 100644 (file)
--- a/makefile
+++ b/makefile
@@ -2,7 +2,7 @@ PN = htsn-common
 SRCS := $(shell find src/ -type f -name '*.hs')
 BINS = $(patsubst src%.hs, dist/build%.o, $(SRCS))
 
-.PHONY : dist hlint
+.PHONY : dist doc hlint
 
 $(BINS): $(PN).cabal $(SRCS)
        echo $(BINS)
@@ -17,7 +17,7 @@ profile: $(PN).cabal $(SRCS)
                                   --prefix=/
        runghc Setup.hs build
 
-doc: $(PN).cabal $(SRCS)
+doc:
        runghc Setup.hs configure --user --prefix=/
        runghc Setup.hs hscolour --executables
        runghc Setup.hs haddock --internal    \

diff --git a/src/Network/Services/TSN/Logging.hs b/src/Network/Services/TSN/Logging.hs
index a20a8977ff05d6ddd5719c461b322f8c1dac8b44..f4cf072e1f8f504c792a6e3ef330c8d69cfceb41 100644 (file)
--- a/src/Network/Services/TSN/Logging.hs
+++ b/src/Network/Services/TSN/Logging.hs
@@ -1,3 +1,5 @@
+-- | Provide convenience functions for logging to the HSLogger "root"
+--   logger.
 module Network.Services.TSN.Logging (
   init_logging,
   log_debug,
@@ -48,12 +50,18 @@ log_warning = warningM rootLoggerName
 --   logger provided by HSLogger. We remove all of its handlers so
 --   that it does nothing; then we conditionally add back two handlers
 --   -- one for syslog, and one for a normal file -- dependent upon
---   the 'syslog' and 'log_file' configuration items.
+--   the @syslog@ and @log_file@ arguments.
 --
---   Why don't we take a Configuration as an argument? Because it
---   would create circular imports!
-init_logging :: Maybe FilePath -> Priority -> Bool -> IO ()
-init_logging log_file log_level syslog = do
+--   If @syslog@ is 'False' and @log_file@ is 'Nothing'; then nothing
+--   will be logged and the @log_level@ will essentially be ignored
+--   (even though the root logger will have its level set).
+--
+init_logging :: Maybe FilePath -- ^ Path to the log file (optional)
+             -> Bool           -- ^ Log to syslog?
+             -> Priority       -- ^ The priority at and above which
+                               --   to log messages.
+             -> IO ()
+init_logging log_file syslog log_level = do
   -- First set the global log level and clear the default handler.
   let no_handlers = [] :: [GenericHandler a]
   updateGlobalLogger rootLoggerName (setLevel log_level .

diff --git a/src/Network/Services/TSN/Report.hs b/src/Network/Services/TSN/Report.hs
index 2423352776481c5503a918481ccd77d0fd4d40d6..2826608cfccef527ef0aade6063ab39d7f91f452 100644 (file)
--- a/src/Network/Services/TSN/Report.hs
+++ b/src/Network/Services/TSN/Report.hs
@@ -1,4 +1,4 @@
--- | Convenience functions for reporting (display and/or logging)
+-- | Convenience functions for reporting (displaying and/or logging)
 --   status messages.
 --
 module Network.Services.TSN.Report (
@@ -30,7 +30,7 @@ report_debug s = do
 
 
 -- | Display and log an error condition. This will prefix the error
---   with "ERROR: " when displaying (but not logging) it so that it
+--   with \"ERROR: \" when displaying (but not logging) it so that it
 --   stands out.
 --
 report_error :: String -> IO ()
@@ -48,7 +48,7 @@ report_info s = do
 
 
 -- | Display and log a warning. This will prefix the warning with
---   "WARNING: " when displaying (but not logging) it so that it
+--   \"WARNING: \" when displaying (but not logging) it so that it
 --   stands out.
 --
 report_warning :: String -> IO ()

diff --git a/src/Network/Services/TSN/Terminal.hs b/src/Network/Services/TSN/Terminal.hs
index e24d23cb48ccbb3bd5c15c47cd11aa5f42af3aad..c36e90c89461469e1b04745d75a8c612e1e54ad2 100644 (file)
--- a/src/Network/Services/TSN/Terminal.hs
+++ b/src/Network/Services/TSN/Terminal.hs
@@ -1,3 +1,7 @@
+-- | Terminal output functions for displaying informational
+--   messages. The output is color-coded according to severity, and is
+--   designed at the moment for consoles with a dark background.
+--
 module Network.Services.TSN.Terminal (
   display_debug,
   display_error,
@@ -55,25 +59,28 @@ display_sent = hPutStrColor stdout Green
 
 
 -- | Display debug text on the console. Don't automatically append a
---   newline in case the raw text is needed for, uh, debugging.
+--   newline in case the raw text is needed for, uh, debugging. The
+--   text color is not altered.
 --
 display_debug :: String -> IO ()
 display_debug = putStr
 
 
--- | Display an informational message on the console.
+-- | Display an informational message on the console in cyan.
 --
 display_info :: String -> IO ()
 display_info = hPutStrColorLn stdout Cyan
 
 
--- | Display a warning on the console. Uses stderr instead of stdout.
+-- | Display a warning on the console in yello. Uses stderr instead of
+--   stdout.
 --
 display_warning :: String -> IO ()
 display_warning = hPutStrColorLn stderr Yellow
 
 
--- | Display an error on the console. Uses stderr instead of stdout.
+-- | Display an error on the console in red. Uses stderr instead of
+--   stdout.
 --
 display_error :: String -> IO ()
 display_error = hPutStrColorLn stderr Red