export additional functions

 - add haddock documentation

output-blocks/output-blocks.cabal

@@ -5,7 +5,7 @@ cabal-version: 1.12
 -- see: https://github.com/sol/hpack
 
 name:           output-blocks
-version:        0.3.0.1
+version:        0.3.0.2
 build-type:     Simple
 
 library

output-blocks/package.yaml

@@ -1,6 +1,6 @@
 ---
 name: output-blocks
-version: 0.3.0.1
+version: 0.3.0.2
 extra-source-files: [ ]
 build-tools: [ ]
 ghc-options:

output-blocks/src/Control/OutputCapable/Blocks/Generic/Type.hs

@@ -2,10 +2,16 @@
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE LambdaCase #-}
 {-# LANGUAGE MultiParamTypeClasses #-}
+{-|
+Provides an Algebraic Data Type to represent 'GenericOutput'.
+This can be useful in cases where the raw representation needs to be persited
+or for converting the type of 'GenericOutputCapable'.
+-}
 module Control.OutputCapable.Blocks.Generic.Type
     ( GenericOutput (..)
     , foldrOutput
     , getOutputSequence
+    , getOutputSequenceAndResult
     , getOutputSequenceWithRating
     , inspectTranslations
     , toOutputCapable
@@ -40,16 +46,27 @@ The result can be converted into any member of the class.
 -}
 data GenericOutput language element
     = Assertion Bool [GenericOutput language element]
+    -- ^ abortion is expected at 'False'
     | Image FilePath
+    -- ^ a single image
     | Images (Map String FilePath)
+    -- ^ multiple images with a text tag that is to be printed (e.g. a number)
     | Paragraph [GenericOutput language element]
+    -- ^ to group (and separate) output
     | Refuse [GenericOutput language element]
+    -- ^ abort with output
     | Enumerated [([GenericOutput language element], [GenericOutput language element])]
+    -- ^ an enumeration with the enumerator first and content second
     | Itemized [[GenericOutput language element]]
+    -- ^ like enumeration (but without enumerator)
     | Indented [GenericOutput language element]
+    -- ^ for indenting output
     | Latex String
+    -- ^ latex code (for formulas and text blocks only)
     | Code (Map language String)
+    -- ^ to output as text with fixed width, providing translations
     | Translated (Map language String)
+    -- ^ normal text with translations
     | Special element
     -- ^ allows abbreviating several complex parts
     --   which have special rendering functions
@@ -156,6 +173,10 @@ getOutputSequenceWithRating = getOutputSequenceAndResult
 {-|
 Converts 'GenericOutputCapable' value using 'GenericOutput'
 into a result and a list of 'GenericOutput'
+
+Consider using 'getOutputSequenceWithRating'
+or even more specific versions of 'Control.OutputCapable.Blocks.Type'
+in order to get better error messages on implementation errors.
 -}
 getOutputSequenceAndResult
   :: Functor m

output-blocks/src/Control/OutputCapable/Blocks/Type.hs

@@ -36,6 +36,8 @@ module Control.OutputCapable.Blocks.Type (
   getSpecialOutputSequenceWithRating,
   specialToOutputCapable,
   withRefusal,
+  -- ** other
+  checkTranslation,
   ) where
 
 import qualified Control.OutputCapable.Blocks.Generic.Type as Generic (
@@ -62,33 +64,58 @@ import Data.List                        ((\\))
 import Data.Map                         (Map)
 import Data.Traversable                 (for)
 
+-- | 'GenericOutput' but with translations fixed to 'Language'
 type SpecialOutput = GenericOutput Language
+
+-- | 'SpecialOutput' without 'Special' elements
 type Output = SpecialOutput ()
 
+{-|
+Converts non graded 'OutputCapable' value using 'GenericOutput'
+into a list of 'Output'
+-}
 getOutputSequence :: Functor m => LangM (ReportT Output m) -> m [Output]
 getOutputSequence = Generic.getOutputSequence English
 
+{-|
+Converts graded 'OutputCapable' value using 'GenericOutput'
+into a rating and a list of 'Output'
+-}
 getOutputSequenceWithRating
   :: Functor m
   => Rated (ReportT Output m)
   -> m (Maybe Rational, [Output])
 getOutputSequenceWithRating = Generic.getOutputSequenceWithRating English
 
+{- |
+Convert a list of 'Output' into any instance of 'OutputCapable'
+-}
 toOutputCapable :: OutputCapable m => [Output] -> LangM m
 toOutputCapable = Generic.toOutputCapable pure
 
+{-|
+Converts non graded 'OutputCapable' value using 'GenericOutput'
+into a list of 'SpecialOutput'
+-}
 getSpecialOutputSequence
   :: Functor m
   => LangM (ReportT (SpecialOutput element) m)
   -> m [SpecialOutput element]
 getSpecialOutputSequence = Generic.getOutputSequence English
 
+{-|
+Converts graded 'OutputCapable' value using 'GenericOutput'
+into a rating and a list of 'SpecialOutput'
+-}
 getSpecialOutputSequenceWithRating
   :: Functor m
   => Rated (ReportT (SpecialOutput element) m)
   -> m (Maybe Rational, [SpecialOutput element])
 getSpecialOutputSequenceWithRating = Generic.getOutputSequenceWithRating English
 
+{- |
+Convert a list of 'SpecialOutput' into any instance of 'OutputCapable'
+-}
 specialToOutputCapable
   :: OutputCapable m
   => (element -> LangM m)