Skip to content
← Back

src/syntax/process/attach_doc_comments.ghul

1
namespace Syntax.Process is
2
use Source
3
use Trees
4
5
use Lexical.TRIVIA
6
7
// Gives each declaration the `///` block written directly above it:
8
// lines of doc comment on consecutive lines, the last of them on the
9
// line before the declaration or, where pragmas precede it, before
10
// its outermost pragma. Anything between the block and that line
11
// detaches it. The text is the lines with `///` and one following
12
// space removed, joined with newlines, and is otherwise left alone.
13
//
14
// Only declarations are walked: a function or property body holds
15
// nothing that takes a doc comment.
16
class ATTACH_DOC_COMMENTS: Visitor is
17
_blocks: Collections.MAP[int, string]
18
19
// The first line of the outermost pragma wrapping the next
20
// declaration, or -1 when no pragma is pending.
21
_pragma_line: int
22
23
init() is
24
super.init()
25
26
_blocks = Collections.MAP[int, string]()
27
_pragma_line = -1
28
si
29
30
apply(source_file: Compiler.SOURCE_FILE) is
31
_blocks = _collect_blocks(source_file.trivia)
32
_pragma_line = -1
33
34
if _blocks.count > 0 then
35
source_file.definition.walk(self)
36
fi
37
si
38
39
// Keyed by the line after each block's last line, which is the
40
// line a declaration has to start on to take the block.
41
_collect_blocks(trivia: Collections.Iterable[TRIVIA]?) -> Collections.MAP[int, string] is
42
let result = Collections.MAP[int, string]()
43
44
if !trivia? then
45
return result
46
fi
47
48
let lines = Collections.LIST[string]()
49
let last_line mut = -1
50
51
for t in trivia do
52
if let dc: TRIVIA.DOC_COMMENT = t then
53
let line = dc.location.start_line
54
55
if lines.count > 0 /\ line != last_line + 1 then
56
result[last_line + 1] = string.join("\n", lines)
57
lines.clear()
58
fi
59
60
lines.add(_strip_marker(dc.text))
61
last_line = line
62
fi
63
od
64
65
if lines.count > 0 then
66
result[last_line + 1] = string.join("\n", lines)
67
fi
68
69
return result
70
si
71
72
_strip_marker(text: string) -> string is
73
let start = if text.length > 3 /\ text[3] == ' ' then 4 else 3 fi
74
75
return text.substring(start)
76
si
77
78
_attach(definition: Definitions.Definition) is
79
let line =
80
if _pragma_line >= 0 then
81
_pragma_line
82
else
83
definition.location.start_line
84
fi
85
86
_pragma_line = -1
87
88
let text: string mut = ""
89
90
if _blocks.try_get_value(line, text ref) then
91
definition.doc = text
92
fi
93
si
94
95
_skip() is
96
_pragma_line = -1
97
si
98
99
pre(pragma: Definitions.PRAGMA) -> bool is
100
if _pragma_line < 0 then
101
_pragma_line = pragma.location.start_line
102
fi
103
104
return false
105
si
106
107
pre(`class: Definitions.CLASS) -> bool is
108
_attach(`class)
109
return false
110
si
111
112
pre(`trait: Definitions.TRAIT) -> bool is
113
_attach(`trait)
114
return false
115
si
116
117
pre(`struct: Definitions.STRUCT) -> bool is
118
_attach(`struct)
119
return false
120
si
121
122
pre(`union: Definitions.UNION) -> bool is
123
_attach(`union)
124
return false
125
si
126
127
pre(variant: Definitions.VARIANT) -> bool is
128
_attach(variant)
129
return true
130
si
131
132
pre(`enum: Definitions.ENUM) -> bool is
133
_attach(`enum)
134
return false
135
si
136
137
pre(enum_member: Definitions.ENUM_MEMBER) -> bool is
138
_attach(enum_member)
139
return true
140
si
141
142
pre(function: Definitions.FUNCTION) -> bool is
143
_attach(function)
144
return true
145
si
146
147
pre(property: Definitions.PROPERTY) -> bool is
148
_attach(property)
149
return true
150
si
151
152
pre(`namespace: Definitions.NAMESPACE) -> bool is
153
_skip()
154
return false
155
si
156
157
pre(`partial: Definitions.PARTIAL) -> bool is
158
_skip()
159
return false
160
si
161
162
pre(`impl: Definitions.IMPL) -> bool is
163
_skip()
164
return false
165
si
166
167
pre(`use: Definitions.USE) -> bool is
168
_skip()
169
return true
170
si
171
172
pre(super_call: Definitions.SUPER_CALL) -> bool is
173
_skip()
174
return true
175
si
176
177
pre(indexer: Definitions.INDEXER) -> bool is
178
_skip()
179
return true
180
si
181
182
pre(variable: Variables.VARIABLE) -> bool is
183
_skip()
184
return true
185
si
186
si
187
si