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