git.iko.soy/elk
on 00a3069 help sign in
elk/src/Reporting/Error/Docs.hs
133 lines 4.4 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
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
30-- TO REPORT
33toReport :: Code.Source -> Error -> Report.Report
34toReport source err =
35 case err of
36 NoDocs ->
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 ]
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 ]
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 error "TODO OnlyInDocs"
92 )
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"
103 )
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 ]
117 )
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 ]
133 )