fix various documentation issues

README.md

@@ -78,8 +78,10 @@ If you use another way of keeping track of position information, you will need t
 Once your reports are created, you will need to add them inside the diagnostic using `addReport`.
 You will also need to put your files into the diagnostic with `addFile`, else lines won't be printed and you will get `<no-line>` in your reports.
 
-After all of this is done, you may choose to either print the diagnostic onto a handle using `printDiagnostic`
-or export it to JSON with `diagnosticToJson` or the `ToJSON` class of Aeson (the output format is documented under the `diagnosticToJson` function).
+After all of this is done, you may choose to either:
+- print the diagnostic onto a file `Handle` (most likely `stdout` or `stderr`) using `printDiagnostic`;
+- create a `Doc`ument which can be further altered using `prettyDiagnostic`;
+- or export it to JSON with `diagnosticToJson` or the `ToJSON` class of Aeson (the output format is documented under the `diagnosticToJson` function).
 
 ## Example
 
@@ -103,7 +105,7 @@ let diagnostic' = addReport diagnostic beautifulExample
 printDiagnostic stdout True True 4 defaultStyle diagnostic'
 ```
 
-More examples are given in the [`test/rendering`](./test/rendering) folder.
+More examples are given in the [`test/rendering`](./test/rendering) folder (execute `stack test` to see the output).
 
 ## TODO list
 
@@ -113,4 +115,4 @@ More examples are given in the [`test/rendering`](./test/rendering) folder.
 
 This work is licensed under the BSD-3 clause license.
 
-Copyright (c) 2021- Mesabloo, all rights reserved.
+Copyright (c) 2021-2022 Mesabloo, all rights reserved.

diagnose.cabal

@@ -17,7 +17,7 @@ homepage:       https://github.com/mesabloo/diagnose#readme
 bug-reports:    https://github.com/mesabloo/diagnose/issues
 author:         Ghilain Bergeron
 maintainer:     Ghilain Bergeron
-copyright:      2021- Ghilain Bergeron
+copyright:      2021-2022 Ghilain Bergeron
 license:        BSD3
 license-file:   LICENSE
 build-type:     Simple

package.yaml

@@ -3,7 +3,7 @@ version: 1.9.0
 github: "mesabloo/diagnose"
 license: BSD3
 author: "Ghilain Bergeron"
-copyright: "2021- Ghilain Bergeron"
+copyright: "2021-2022 Ghilain Bergeron"
 category: "Error Reporting"
 
 dependencies:

src/Error/Diagnose.hs

@@ -10,9 +10,12 @@ module Error.Diagnose
     -- ** Creating diagnostics from reports
     -- $create_diagnostic
 
-    -- *** Pretty-printing a diagnostic
+    -- *** Pretty-printing a diagnostic onto a file 'System.IO.Handle'
     -- $diagnostic_pretty
 
+    -- *** Pretty-printing a diagnostic as a 'PrettyPrinter.Doc'ument
+    -- $diagnostic_to_doc
+
     -- *** Exporting a diagnostic to JSON
     -- $diagnostic_json
 
@@ -96,13 +99,13 @@ import Error.Diagnose.Style as Export
 --
 --   Markers put in the report can be one of (the colors specified are used only when pretty-printing):
 --
---   - A 'This' marker, which is the primary marker of the report.
+--   - A 'Error.Diagnose.Report.This' marker, which is the primary marker of the report.
 --     While it is allowed to have multiple of these inside one report, it is encouraged not to, because the position at the top of
---     the report will only be the one of the /first/ 'This' marker, and because the resulting report may be harder to understand.
+--     the report will only be the one of the /first/ 'Error.Diagnose.Report.This' marker, and because the resulting report may be harder to understand.
 --
 --         This marker is output in red in an error report, and yellow in a warning report.
 --
---   - A 'Where' marker contains additional information/provides context to the error/warning report.
+--   - A 'Error.Diagnose.Report.Where' marker contains additional information/provides context to the error/warning report.
 --     For example, it may underline where a given variable @x@ is bound to emphasize it.
 --
 --         This marker is output in blue.
@@ -118,7 +121,8 @@ import Error.Diagnose.Style as Export
 --   and returns a 'Diagnostic') to insert a new report inside the diagnostic, or 'addFile' (which takes a 'Diagnostic', a 'FilePath' and a @['String']@,
 --   and returns a 'Diagnostic') to insert a new file reference in the diagnostic.
 --
---   You can then either pretty-print the diagnostic obtained (which requires all messages to be instances of the 'Text.PrettyPrint.ANSI.Leijen.Pretty')
+--   You can then either pretty-print the diagnostic obtained (which requires all messages to be instances of the 'Prettyprinter.Pretty')
+--   -- directly onto a file handle or as a plain 'Prettyprinter.Doc'ument --
 --   or export it to a lazy JSON 'Data.Bytestring.Lazy.ByteString' (e.g. in a LSP context).
 
 -- $diagnostic_pretty
@@ -158,6 +162,12 @@ import Error.Diagnose.Style as Export
 --
 --   - And finally the 'Diagnostic' to output.
 
+-- $diagnostic_to_doc
+--
+-- 'Diagnostic's can be “output” (at least ready to be rendered) to a 'Prettyprinter.Doc', which allows it to be easily added to other 'Prettyprinter.Doc' outputs.
+-- This makes it easy to customize the error messages further (though not the internal parts, only adding to it).
+-- As a 'Prettyprinter.Doc', there is also the possibility of altering internal annotations (styles) much easier (although this is already possible when printing the diagnostic).
+
 -- $diagnostic_json
 --
 --   'Diagnostic's can be exported to a JSON record of the following type, using the 'diagnosticToJson' function:

src/Error/Diagnose/Compat/Megaparsec.hs

@@ -11,7 +11,7 @@
 -- |
 -- Module      : Error.Diagnose.Compat.Megaparsec
 -- Description : Compatibility layer for megaparsec
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable

src/Error/Diagnose/Compat/Parsec.hs

@@ -7,7 +7,7 @@
 -- |
 -- Module      : Error.Diagnose.Compat.Parsec
 -- Description : Compatibility layer for parsec
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable

src/Error/Diagnose/Diagnostic.hs

@@ -3,7 +3,7 @@
 -- |
 -- Module      : Error.Diagnose.Diagnostic
 -- Description : Diagnostic definition and pretty printing
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable

src/Error/Diagnose/Diagnostic/Internal.hs

@@ -4,7 +4,7 @@
 -- |
 -- Module      : Error.Diagnose.Diagnostic.Internal
 -- Description : Internal workings for diagnostic definitions and pretty printing.
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable

src/Error/Diagnose/Position.hs

@@ -7,7 +7,7 @@
 -- |
 -- Module      : Error.Diagnose.Diagnostic
 -- Description : Defines location information as a simple record.
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable

src/Error/Diagnose/Report.hs

@@ -1,7 +1,7 @@
 -- |
 -- Module      : Error.Diagnose.Report
 -- Description : Report definition and pretty printing
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable

src/Error/Diagnose/Report/Internal.hs

@@ -10,7 +10,7 @@
 -- |
 -- Module      : Error.Diagnose.Report.Internal
 -- Description : Internal workings for report definitions and pretty printing.
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable

src/Error/Diagnose/Style.hs

@@ -1,7 +1,7 @@
 -- |
 -- Module      : Error.Diagnose.Style
 -- Description : Custom style definitions
--- Copyright   : (c) Mesabloo, 2021
+-- Copyright   : (c) Mesabloo, 2021-2022
 -- License     : BSD3
 -- Stability   : experimental
 -- Portability : Portable