Permalink
Browse files

documentation pass

  • Loading branch information...
ekmett committed Aug 31, 2011
1 parent 8600b8e commit 22c315ff86b145f5dbf4ac50de163621e144b05f
View
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta
( module Text.Trifecta.Diagnostic
, module Text.Trifecta.Parser
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic
(
-- * Diagnostics
@@ -1,4 +1,16 @@
{-# LANGUAGE MultiParamTypeClasses, FlexibleInstances, FunctionalDependencies, FlexibleContexts, UndecidableInstances #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Class
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+-- Provides a class for logging and throwing expressive diagnostics.
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Class
( MonadDiagnostic(..)
) where
@@ -1,3 +1,15 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Combinators
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+-- Combinators for throwing and logging expressive diagnostics
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Combinators
( fatal
, err
@@ -1,3 +1,15 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Err
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+-- The unlocated error type used internally within the parser.
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Err
( Err(..)
, knownErr
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Err.Log
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Err.Log
( ErrLog(..)
) where
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Err.State
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Err.State
( ErrState(..)
) where
@@ -1,3 +1,15 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Level
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+-- A fairly straightforward set of common error levels.
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Level
( DiagnosticLevel(..)
) where
@@ -7,13 +19,14 @@ import Data.Semigroup
import Text.PrettyPrint.Free
import System.Console.Terminfo.PrettyPrint
+-- | The severity of an error (or message)
data DiagnosticLevel
- = Verbose !Int -- a comment we should only show to the excessively curious
- | Note -- a comment
- | Warning -- a warning, computation continues
- | Error -- a user specified error
- | Fatal -- a user specified fatal error
- | Panic -- a non-maskable death sentence thrown by the parser itself
+ = Verbose !Int -- ^ a comment we should only show to the excessively curious
+ | Note -- ^ a comment
+ | Warning -- ^ a warning, computation continues
+ | Error -- ^ a user specified error
+ | Fatal -- ^ a user specified fatal error
+ | Panic -- ^ a non-maskable death sentence thrown by the parser itself
deriving (Eq,Show,Read)
instance Ord DiagnosticLevel where
@@ -36,12 +49,14 @@ instance Ord DiagnosticLevel where
compare Panic Panic = EQ
compare Panic _ = GT
+-- | Compute the maximum of two diagnostic levels
instance Semigroup DiagnosticLevel where
(<>) = max
instance Pretty DiagnosticLevel where
pretty p = prettyTerm p *> empty
+-- | pretty print as a color coded description
instance PrettyTerm DiagnosticLevel where
prettyTerm (Verbose n) = blue $ text "verbose (" <> prettyTerm n <> char ')'
prettyTerm Note = black $ text "note"
@@ -1,4 +1,16 @@
{-# LANGUAGE FlexibleContexts, DeriveDataTypeable #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Prim
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+-- Rich diagnostics
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Prim
( Diagnostic(..)
, tellDiagnostic
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Rendering
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Rendering
( Renderable(..)
, Source, rendering
@@ -1,4 +1,15 @@
{-# LANGUAGE MultiParamTypeClasses #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Rendering.Caret
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Rendering.Caret
( Caret(..)
, caret
@@ -1,4 +1,15 @@
{-# LANGUAGE MultiParamTypeClasses #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Rendering.Fixit
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Rendering.Fixit
( Fixit(..)
, drawFixit
@@ -1,10 +1,22 @@
{-# LANGUAGE TypeSynonymInstances, FlexibleInstances #-}
--- | Diagnostics rendering
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Rendering.Prim
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
--
--- The type for Lines will very likely change over time, so we can draw lit up control
--- characters for ^Z, ^[, <0xff>, etc. this will make for much nicer diagnostics when
--- working with protocols!
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+-- The type for Lines will very likely change over time, to enable drawing
+-- lit up multi-character versions of control characters for @^Z@, @^[@,
+-- @<0xff>@, etc. This will make for much nicer diagnostics when
+-- working with protocols.
+--
+-----------------------------------------------------------------------------
+
module Text.Trifecta.Diagnostic.Rendering.Prim
( Rendering(..)
, nullRendering
@@ -1,4 +1,15 @@
{-# LANGUAGE MultiParamTypeClasses #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Diagnostic.Rendering.Span
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Diagnostic.Rendering.Span
( Span(..)
, span
View
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Highlight
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Highlight
( module Text.Trifecta.Highlight.Prim
, module Text.Trifecta.Highlight.Class
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Highlight.Class
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Highlight.Class
( Highlightable(..)
) where
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Highlight.Effects
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Highlight.Effects
( highlightEffects
, pushToken
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Highlight.Prim
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Highlight.Prim
( Highlight(..)
, Highlights
@@ -1,4 +1,15 @@
{-# LANGUAGE OverloadedStrings #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Highlight.Rendering.HTML
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Highlight.Rendering.HTML
( Doc(..)
, doc
View
@@ -1,3 +1,14 @@
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Parser
+-- Copyright : (C) 2011 Edward Kmett,
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Parser
( module Text.Trifecta.Parser.Prim
, module Text.Trifecta.Parser.ByteString
@@ -1,5 +1,16 @@
{-# LANGUAGE MultiParamTypeClasses, FunctionalDependencies, UndecidableInstances, FlexibleInstances, FlexibleContexts, PatternGuards #-}
{-# OPTIONS_GHC -fspec-constr -fspec-constr-count=8 #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Parser.Char
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+----------------------------------------------------------------------------
module Text.Trifecta.Parser.Char
( oneOf -- :: MonadParser m => [Char] -> m Char
, noneOf -- :: MonadParser m => [Char] -> m Char
View
@@ -1,5 +1,16 @@
{-# LANGUAGE MultiParamTypeClasses, BangPatterns, MagicHash, UnboxedTuples, TypeFamilies #-}
--- | harder, better, faster, stronger...
+-----------------------------------------------------------------------------
+-- |
+-- Module : Text.Trifecta.Parser.It
+-- Copyright : (C) 2011 Edward Kmett
+-- License : BSD-style (see the file LICENSE)
+--
+-- Maintainer : Edward Kmett <ekmett@gmail.com>
+-- Stability : experimental
+-- Portability : non-portable
+--
+-- harder, better, faster, stronger...
+----------------------------------------------------------------------------
module Text.Trifecta.Parser.It
( It(Pure, It)
, needIt
Oops, something went wrong.

0 comments on commit 22c315f

Please sign in to comment.