Repository navigation
Expand file tree
/
Copy pathdoxygen-python.awk
More file actions
362 lines (350 loc) · 12.4 KB
/
Copy pathdoxygen-python.awk
File metadata and controls
362 lines (350 loc) · 12.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
#!/usr/bin/awk -f
## @file doxygen-python.awk
## @brief Translates supported Python docstring fields for Doxygen.
## @details
## Preserves Python source and rewrites only governed structured fields inside
## conservatively recognized docstrings. This is an intentionally small
## documentation translator, not a complete Python parser. See ADR-001,
## ADR-002, ADR-003, ADR-009, and ADR-010 before widening recognition or
## representation behavior.
## @rule initialize_filter
## @brief Initializes parser state and consumes the `--strict` option.
BEGIN {
strict = 0
diagnostics = 0
in_docstring = 0
in_declaration = 0
module_doc_possible = 1
pending_suite = 0
for (i = 1; i < ARGC; i++) {
if (ARGV[i] == "--strict") {
strict = 1
delete ARGV[i]
} else if (ARGV[i] == "--") {
delete ARGV[i]
}
}
}
## @fn leading_width(line)
## @brief Returns the leading indentation width of a source line.
## @details
## Copies the input into scratch storage before removing everything after the
## leading spaces and tabs. The caller-supplied value is not modified.
##
## @param line Source line to inspect.
## @local s Scratch copy used while measuring indentation.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Nothing is written to STDERR.
##
## @returns Number of leading space and tab bytes.
function leading_width(line, s) {
s = line
sub(/[^ \t].*$/, "", s)
return length(s)
}
## @fn warn(message)
## @brief Records and emits one translation diagnostic.
## @details
## Increments the global diagnostic count and writes one location-qualified
## warning for the current input record.
##
## @param message Stable diagnostic text.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Writes one warning containing the current file name and record number.
##
## @par Side Effects
## Increments the global `diagnostics` counter.
##
## @returns No meaningful value; callers use the function for its side effects.
function warn(message) {
diagnostics++
printf "%s:%d: warning: %s\n", FILENAME, FNR, message > "/dev/stderr"
}
## @fn is_blank_or_comment(line)
## @brief Tests for input that may precede a suite's first statement.
## @details
## Removes leading horizontal whitespace from a scratch copy and then checks
## whether the remaining input is empty or begins with a comment marker.
##
## @param line Source line to inspect.
## @local s Scratch copy used while testing the source line.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Nothing is written to STDERR.
##
## @returns One for blank or comment-only input; zero otherwise.
function is_blank_or_comment(line, s) {
s = line
sub(/^[ \t]*/, "", s)
return (s == "" || s ~ /^#/)
}
## @fn is_declaration_start(line)
## @brief Recognizes governed class and function declaration starts.
## @details
## Removes leading horizontal whitespace from a scratch copy and recognizes only
## the conservative declaration-start forms governed by ADR-009.
##
## @param line Source line to inspect.
## @local s Scratch copy used while testing the declaration syntax.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Nothing is written to STDERR.
##
## @returns One for a supported declaration start; zero otherwise.
function is_declaration_start(line, s) {
s = line
sub(/^[ \t]*/, "", s)
return (s ~ /^(async[ \t]+)?def[ \t]+[A-Za-z_][A-Za-z0-9_]*[ \t]*\(/ || s ~ /^class[ \t]+[A-Za-z_][A-Za-z0-9_]*/)
}
## @fn declaration_header_complete(line)
## @brief Tests whether a declaration header reaches its suite-opening colon.
## @details
## Removes trailing horizontal whitespace and checks for a final colon. This is
## intentionally narrower than Python lexical parsing and does not interpret
## inline comments, strings, annotations, or balanced delimiters.
##
## @param line Physical declaration-header line to inspect.
## @local s Scratch copy used while testing the line ending.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Nothing is written to STDERR.
##
## @returns One when the last non-whitespace byte is a colon; zero otherwise.
function declaration_header_complete(line, s) {
s = line
sub(/[ \t]+$/, "", s)
return (s ~ /:$/)
}
## @fn starts_docstring(line)
## @brief Tests for a supported triple-double-quoted docstring start.
## @details
## Removes leading horizontal whitespace and recognizes the ordinary delimiter
## plus the `r` and `R` raw prefixes required by ADR-009.
##
## @param line Source line to inspect.
## @local s Scratch copy used while testing the opening delimiter.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Nothing is written to STDERR.
##
## @returns One when the first non-whitespace bytes open a supported form.
function starts_docstring(line, s) {
s = line
sub(/^[ \t]*/, "", s)
if (substr(s, 1, 3) == "\"\"\"") return 1
return ((substr(s, 1, 1) == "r" || substr(s, 1, 1) == "R") && substr(s, 2, 3) == "\"\"\"")
}
## @fn docstring_open_width(line)
## @brief Returns the byte width of a supported docstring opening form.
## @details
## Distinguishes ordinary and raw supported openings after removing leading
## horizontal whitespace. Unsupported forms return zero.
##
## @param line Source line beginning with a possible docstring opening.
## @local s Scratch copy used while identifying the opening form.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Nothing is written to STDERR.
##
## @returns Three for ordinary, four for raw, or zero for unsupported input.
function docstring_open_width(line, s) {
s = line
sub(/^[ \t]*/, "", s)
if (substr(s, 1, 3) == "\"\"\"") return 3
if ((substr(s, 1, 1) == "r" || substr(s, 1, 1) == "R") && substr(s, 2, 3) == "\"\"\"") return 4
return 0
}
## @fn closes_same_line(line)
## @brief Tests whether a recognized docstring closes on its opening line.
## @details
## Identifies the governed opening width and searches the remainder of the line
## for a second triple-double-quote delimiter.
##
## @param line Recognized docstring start line.
## @local s Scratch copy used while validating the opening delimiter.
## @local width Width of the supported opening form.
## @local rest Source text following the opening delimiter.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written to STDOUT.
## @par STDERR
## Nothing is written to STDERR.
##
## @returns One when a second delimiter occurs on the line; zero otherwise.
function closes_same_line(line, s, width, rest) {
s = line
sub(/^[ \t]*/, "", s)
width = docstring_open_width(s)
if (width == 0) return 0
rest = substr(s, width + 1)
return (index(rest, "\"\"\"") > 0)
}
## @fn translate_doc_line(line)
## @brief Translates one supported structured field inside a docstring.
## @details
## Preserves indentation, recognizes only governed Sphinx field forms, and
## returns the original line whenever no safe translation exists. Malformed
## governed fields are diagnosed and left unchanged. ADR-003 and ADR-010 permit
## titled-paragraph translations to contain one embedded newline so Doxygen
## receives a separate paragraph title and body.
##
## @param line Physical docstring line to inspect.
## @local indent Leading horizontal whitespace preserved in translated output.
## @local body Docstring content after indentation is removed.
## @local name Parameter or type-field name extracted from a structured field.
## @local desc Description or maintained type value extracted from a supported
## field.
## @local exc Exception name extracted from a `:raises` field.
##
## @par STDIN
## Nothing is read directly from STDIN.
## @par STDOUT
## Nothing is written directly to STDOUT.
## @par STDERR
## Malformed governed fields are reported through `warn()`.
##
## @returns Translated text, or original text when no safe translation exists.
function translate_doc_line(line, indent, body, name, desc, exc) {
indent = line
sub(/[^ \t].*$/, "", indent)
body = substr(line, length(indent) + 1)
if (body ~ /^:param[ \t]+[^:]+:/) {
name = body
sub(/^:param[ \t]+/, "", name)
desc = name
sub(/:.*/, "", name)
sub(/^[^:]*:[ \t]*/, "", desc)
if (name == "" || name ~ /[ \t]/) { warn("malformed :param field"); return line }
return indent "@param " name (desc == "" ? "" : " " desc)
}
if (body ~ /^:param([ \t]|:|$)/) { warn("malformed :param field"); return line }
if (body ~ /^:returns:[ \t]*/) {
desc = body
sub(/^:returns:[ \t]*/, "", desc)
if (desc == "") { warn("malformed :returns field"); return line }
return indent "@return " desc
}
if (body ~ /^:returns([ \t]|$)/) { warn("malformed :returns field"); return line }
if (body ~ /^:raises[ \t]+[^:]+:/) {
exc = body
sub(/^:raises[ \t]+/, "", exc)
desc = exc
sub(/:.*/, "", exc)
sub(/^[^:]*:[ \t]*/, "", desc)
if (exc == "" || exc ~ /[ \t]/) { warn("malformed :raises field"); return line }
return indent "@exception " exc (desc == "" ? "" : " " desc)
}
if (body ~ /^:raises([ \t]|:|$)/) { warn("malformed :raises field"); return line }
if (body ~ /^:yields:[ \t]*/) {
desc = body
sub(/^:yields:[ \t]*/, "", desc)
if (desc == "") { warn("malformed :yields field"); return line }
return indent "@par Yields\n" indent desc
}
if (body ~ /^:yields([ \t]|$)/) { warn("malformed :yields field"); return line }
if (body ~ /^:type[ \t]+[^:]+:/) {
name = body
sub(/^:type[ \t]+/, "", name)
desc = name
sub(/:.*/, "", name)
sub(/^[^:]*:[ \t]*/, "", desc)
if (name == "" || name ~ /[ \t]/ || desc == "") { warn("malformed :type field"); return line }
return indent "@par Type of " name "\n" indent desc
}
if (body ~ /^:type([ \t]|:|$)/) { warn("malformed :type field"); return line }
if (body ~ /^:rtype:[ \t]*/) {
desc = body
sub(/^:rtype:[ \t]*/, "", desc)
if (desc == "") { warn("malformed :rtype field"); return line }
return indent "@par Return type\n" indent desc
}
if (body ~ /^:rtype([ \t]|$)/) { warn("malformed :rtype field"); return line }
return line
}
## @rule translate_source_record
## @brief Passes source through and translates fields in recognized docstrings.
{
source_line = $0
if (in_docstring) {
if (index(source_line, "\"\"\"") > 0) { in_docstring = 0; print source_line; next }
print translate_doc_line(source_line)
next
}
if (in_declaration) {
if (declaration_header_complete(source_line)) {
in_declaration = 0
pending_suite = 1
pending_indent = declaration_indent
}
print source_line
next
}
if (pending_suite) {
if (is_blank_or_comment(source_line)) { print source_line; next }
if (leading_width(source_line) > pending_indent && starts_docstring(source_line)) {
pending_suite = 0
if (!closes_same_line(source_line)) in_docstring = 1
print source_line
next
}
pending_suite = 0
}
if (module_doc_possible) {
if (is_blank_or_comment(source_line)) { print source_line; next }
if (leading_width(source_line) == 0 && starts_docstring(source_line)) {
module_doc_possible = 0
if (!closes_same_line(source_line)) in_docstring = 1
print source_line
next
}
if (leading_width(source_line) == 0) module_doc_possible = 0
}
if (is_declaration_start(source_line)) {
declaration_indent = leading_width(source_line)
if (declaration_header_complete(source_line)) {
pending_suite = 1
pending_indent = declaration_indent
} else {
in_declaration = 1
}
}
print source_line
}
## @rule finalize_filter
## @brief Diagnoses unfinished state and enforces strict-mode failure.
END {
if (in_docstring) warn("unterminated recognized docstring")
if (strict && diagnostics > 0) exit 1
}