mirror of
https://github.com/Mesabloo/diagnose.git
synced 2024-09-11 19:27:32 +03:00
fix various documentation issues
This commit is contained in:
parent
da0ccd5933
commit
75816d465c
10
README.md
10
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.
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
@ -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:
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user