git.iko.soy/elk
on 0bdfd73 help sign in
elk/src/Reporting/Error/Docs.hs
140 lines 4.8 kB history raw
1{-# OPTIONS_GHC -Wall #-}
2{-# LANGUAGE OverloadedStrings #-}
3module Reporting.Error.Docs
4 ( Error(..)
5 , toReport
6 )
7 where
10import qualified Elm.Name as N
11import Reporting.Helpers ((<>))
12import qualified Reporting.Helpers as H
13import qualified Reporting.Region as R
14import qualified Reporting.Render.Code as Code
15import qualified Reporting.Report as Report
19data Error
20 = NoDocs R.Region
21 | ImplicitExposing R.Region
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
30-- TO REPORT
33toReport :: Code.Source -> Error -> Report.Report
34toReport source err =
35 case err of
36 NoDocs region ->
37 Report.Report "NO DOCS" region [] $
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 ]
48 ImplicitExposing region ->
49 Report.Report "IMPLICIT EXPOSING" region [] $
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 ]
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!"
72 )
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!"
81 )
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 H.reflow $
92 "Does it need to be added to the `exposing` list as well? Or maybe you removed `"
93 <> N.toString name <> "` and forgot to delete it here?"
94 )
96 OnlyInExports name region ->
97 Report.Report "DOCS MISTAKE" region [] $
98 Report.toCodeSnippet source region Nothing
99 (
100 H.reflow $
101 "I do not see `" <> N.toString name
102 <> "` in your module documentation, but it is in your `exposing` list:"
103 ,
104 H.stack
105 [ H.reflow $
106 "Add a line like `@docs " <> N.toString name
107 <> "` to your module documentation!"
108 , H.link "Note" "See" "docs" "for more guidance on writing high quality docs."
109 ]
110 )
112 NoComment name region ->
113 Report.Report "NO DOCS" region [] $
114 Report.toCodeSnippet source region Nothing
115 (
116 H.reflow $
117 "The `" <> N.toString name <> "` definition does not have a documentation comment."
118 ,
119 H.stack
120 [ H.reflow $
121 "Add documentation with nice examples of how to use it!"
122 , H.link "Note" "Read" "docs" "for more advice on writing great docs. There are a couple important tricks!"
123 ]
124 )
126 NoAnnotation name region ->
127 Report.Report "NO TYPE ANNOTATION" region [] $
128 Report.toCodeSnippet source region Nothing
129 (
130 H.reflow $
131 "The `" <> N.toString name <> "` definition does not have a type annotation."
132 ,
133 H.stack
134 [ H.reflow $
135 "I use the type variable names from your annotations when generating docs. So if\
136 \ you say `Html msg` in your type annotation, I can use `msg` in the docs and make\
137 \ them a bit clearer. So add an annotation and try to use nice type variables!"
138 , H.link "Note" "Read" "docs" "for more advice on writing great docs. There are a couple important tricks!"
139 ]
140 )