@@ -1,85 +1,133 @@
11{-# OPTIONS_GHC -Wall #-}
22{-# LANGUAGE OverloadedStrings #-}
3−module Reporting.Error.Docs where
3+module Reporting.Error.Docs
4+ ( Error(..)
5+ , toReport
6+ )
7+ where
48
5−import Data.Text (Text)
69
10+import qualified Elm.Name as N
11+import Reporting.Helpers ((<>))
12+import qualified Reporting.Helpers as H
13+import qualified Reporting.Region as R
14+import qualified Reporting.Render.Code as Code
715import qualified Reporting.Report as Report
8−import qualified Reporting.Helpers as Help
9−import Reporting.Helpers ((<>), text)
1016
1117
1218
1319data Error
14− = NoDocs
15− | OnlyInDocs Text [Text]
16− | OnlyInExports [Text]
17− | Duplicates Text
18− | NoComment Text
19− | NoType Text
20+ = NoDocs
21+ | ImplicitExposing
22+ | Duplicate N.Name R.Region R.Region
23+ | OnlyInDocs N.Name R.Region
24+ | OnlyInExports N.Name R.Region
25+ | NoComment N.Name R.Region
26+ | NoAnnotation N.Name R.Region
2027
2128
2229
2330-- TO REPORT
2431
2532
26−toReport :: Error -> Report.Report
27−toReport err =
33+toReport :: Code.Source -> Error -> Report.Report
34+toReport source err =
2835 case err of
2936 NoDocs ->
30− Report.report
31− "DOCUMENTATION ERROR"
32− Nothing
33− ( "You must have a documentation comment between the module\
34− \ declaration and the imports."
35− )
36− ( text "Learn more at <http://package.elm-lang.org/help/documentation-format>"
37− )
37+ Report.Report "NO DOCS" (error "TODO") [] $
38+ H.stack
39+ [
40+ H.reflow $
41+ "You must have a documentation comment between the module\
42+ \ declaration and the imports."
43+ ,
44+ H.reflow
45+ "Learn more at <http://package.elm-lang.org/help/documentation-format>"
46+ ]
3847
39− OnlyInDocs name suggestions ->
40− Report.report
41− "DOCUMENTATION ERROR"
42− Nothing
43− ("Your module documentation includes `" <> name <> "` which is not exported."
44− )
45− ( Help.maybeYouWant (Just "Is it misspelled? Should it be exported?") suggestions
46− )
48+ ImplicitExposing ->
49+ Report.Report "IMPLICIT EXPOSING" (error "TODO") [] $
50+ H.stack
51+ [
52+ H.reflow $
53+ "I need you to be explicit about what this module exposes:"
54+ ,
55+ H.reflow $
56+ "A great API usually hides some implementation details, so it is rare that\
57+ \ everything in the file should be exposed. And requiring package authors\
58+ \ to be explicit about this is a way of adding another quality check before\
59+ \ code gets published. So as you write out the public API, ask yourself if\
60+ \ it will be easy to understand as people read the documentation!"
61+ ]
4762
48− OnlyInExports names ->
49− Report.report
50− "DOCUMENTATION ERROR"
51− Nothing
52− ( "The following exports do not appear in your module documentation: "
53− <> Help.commaSep names
63+ Duplicate name r1 r2 ->
64+ Report.Report "DUPLICATE DOCS" r2 [] $
65+ Report.toCodePair source r1 r2
66+ (
67+ H.reflow $
68+ "There can only be one `" <> N.toString name
69+ <> "` in your module documentation, but it is listed twice:"
70+ ,
71+ "Remove one of them!"
5472 )
55− ( text $
56− "All exports must be listed in the module documentation after a @docs keyword.\n"
57− <> "Learn more at <http://package.elm-lang.org/help/documentation-format>"
73+ (
74+ H.reflow $
75+ "There can only be one `" <> N.toString name
76+ <> "` in your module documentation, but I see two. One here:"
77+ ,
78+ "And another one over here:"
79+ ,
80+ "Remove one of them!"
5881 )
5982
60− Duplicates name ->
61− Report.report
62− "DOCUMENTATION ERROR"
63− Nothing
64− ( "There can only be one `" <> name <> "` in your module documentation."
83+ OnlyInDocs name region ->
84+ Report.Report "DOCS MISTAKE" region [] $
85+ Report.toCodeSnippet source region Nothing
86+ (
87+ H.reflow $
88+ "I do not see `" <> N.toString name
89+ <> "` in the `exposing` list, but it is in your module documentation:"
90+ ,
91+ error "TODO OnlyInDocs"
6592 )
66− ( text "Remove one of them!"
93+
94+ OnlyInExports name region ->
95+ Report.Report "DOCS MISTAKE" region [] $
96+ Report.toCodeSnippet source region Nothing
97+ (
98+ H.reflow $
99+ "I do not see `" <> N.toString name
100+ <> "` in your module documentation, but it is in your `exposing` list:"
101+ ,
102+ error "TODO OnlyInExports"
67103 )
68104
69− NoComment name ->
70− Report.report
71− "DOCUMENTATION ERROR"
72− Nothing
73− ("The `" <> name <> "` definition does not have a documentation comment.")
74− ( text "Learn more at <http://package.elm-lang.org/help/documentation-format>"
105+ NoComment name region ->
106+ Report.Report "NO DOCS" region [] $
107+ Report.toCodeSnippet source region Nothing
108+ (
109+ H.reflow $
110+ "The `" <> N.toString name <> "` definition does not have a documentation comment."
111+ ,
112+ H.stack
113+ [ H.reflow $
114+ "Add documentation with nice examples of how to use it!"
115+ , H.link "Note" "Read" "docs" "for more advice on writing great docs. There are a couple important tricks!"
116+ ]
75117 )
76118
77− NoType name ->
78− Report.report
79− "MISSING ANNOTATION"
80− Nothing
81− ("The `" <> name <> "` definition does not have a type annotation.")
82− ( text $
83− "Adding type annotations is best practice and it gives you a chance to name\n"
84− <> "types and type variables so they are as easy as possible to understand!"
119+ NoAnnotation name region ->
120+ Report.Report "NO TYPE ANNOTATION" region [] $
121+ Report.toCodeSnippet source region Nothing
122+ (
123+ H.reflow $
124+ "The `" <> N.toString name <> "` definition does not have a type annotation."
125+ ,
126+ H.stack
127+ [ H.reflow $
128+ "I use the type variable names from your annotations when generating docs. So if\
129+ \ you say `Html msg` in your type annotation, I can use `msg` in the docs and make\
130+ \ them a bit clearer. So add an annotation and try to use nice type variables!"
131+ , H.link "Note" "Read" "docs" "for more advice on writing great docs. There are a couple important tricks!"
132+ ]
85133 )