From: Michael Orlitzky Date: Thu, 9 Jan 2014 23:31:17 +0000 (-0500) Subject: Add a little more documentation. X-Git-Tag: 0.0.1~2 X-Git-Url: http://gitweb.michael.orlitzky.com/?p=dead%2Fhtsn-common.git;a=commitdiff_plain;h=364709b7a01a7c2b601ff2eae8237c815a858838 Add a little more documentation. Make 'doc' a phony target. --- diff --git a/htsn-common.cabal b/htsn-common.cabal index e5f6939..06b36b0 100644 --- 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 5f49b4b..556200d 100644 --- 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 a20a897..f4cf072 100644 --- 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 2423352..2826608 100644 --- 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 e24d23c..c36e90c 100644 --- 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