2## @file doxygen-python.awk
3## @brief Translates supported Python docstring fields for Doxygen.
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.
11## @rule initialize_filter
12## @brief Initializes parser state and consumes the `--strict` option.
18 module_doc_possible = 1
20 for (i = 1; i < ARGC; i++) {
21 if (ARGV[i] ==
"--strict") {
24 }
else if (ARGV[i] ==
"--") {
30## @fn leading_width(line)
31## @brief Returns the leading indentation width of a source line.
33## Copies the input into scratch storage before removing everything after the
34## leading spaces and tabs. The caller-supplied value is not modified.
36## @param line Source line to inspect.
37## @local s Scratch copy used while measuring indentation.
40## Nothing is read directly from STDIN.
42## Nothing is written to STDOUT.
44## Nothing is written to STDERR.
46## @returns Number of leading space and tab bytes.
49 sub(/[^ \t].*$/,
"", s)
54## @brief Records and emits one translation diagnostic.
56## Increments the global diagnostic count and writes one location-qualified
57## warning for the current input record.
59## @param message Stable diagnostic text.
62## Nothing is read directly from STDIN.
64## Nothing is written to STDOUT.
66## Writes one warning containing the current file name and record number.
69## Increments the global `diagnostics` counter.
71## @returns No meaningful value; callers use the function for its side effects.
74 printf
"%s:%d: warning: %s\n", FILENAME, FNR, message >
"/dev/stderr"
77## @fn is_blank_or_comment(line)
78## @brief Tests for input that may precede a suite's first statement.
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.
83## @param line Source line to inspect.
84## @local s Scratch copy used while testing the source line.
87## Nothing is read directly from STDIN.
89## Nothing is written to STDOUT.
91## Nothing is written to STDERR.
93## @returns One for blank or comment-only input; zero otherwise.
97 return (s ==
"" || s ~ /^#/)
100## @fn is_declaration_start(line)
101## @brief Recognizes governed class and function declaration starts.
103## Removes leading horizontal whitespace from a scratch copy and recognizes only
104## the conservative declaration-start forms governed by ADR-009.
106## @param line Source line to inspect.
107## @local s Scratch copy used while testing the declaration syntax.
110## Nothing is read directly from STDIN.
112## Nothing is written to STDOUT.
114## Nothing is written to STDERR.
116## @returns One for a supported declaration start; zero otherwise.
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_]*/)
123## @fn declaration_header_complete(line)
124## @brief Tests whether a declaration header reaches its suite-opening colon.
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.
130## @param line Physical declaration-header line to inspect.
131## @local s Scratch copy used while testing the line ending.
134## Nothing is read directly from STDIN.
136## Nothing is written to STDOUT.
138## Nothing is written to STDERR.
140## @returns One when the last non-whitespace byte is a colon; zero otherwise.
143 sub(/[ \t]+$/,
"", s)
147## @fn starts_docstring(line)
148## @brief Tests for a supported triple-double-quoted docstring start.
150## Removes leading horizontal whitespace and recognizes the ordinary delimiter
151## plus the `r` and `R` raw prefixes required by ADR-009.
153## @param line Source line to inspect.
154## @local s Scratch copy used while testing the opening delimiter.
157## Nothing is read directly from STDIN.
159## Nothing is written to STDOUT.
161## Nothing is written to STDERR.
163## @returns One when the first non-whitespace bytes open a supported form.
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) ==
"\"\"\"")
171## @fn docstring_open_width(line)
172## @brief Returns the byte width of a supported docstring opening form.
174## Distinguishes ordinary and raw supported openings after removing leading
175## horizontal whitespace. Unsupported forms return zero.
177## @param line Source line beginning with a possible docstring opening.
178## @local s Scratch copy used while identifying the opening form.
181## Nothing is read directly from STDIN.
183## Nothing is written to STDOUT.
185## Nothing is written to STDERR.
187## @returns Three for ordinary, four for raw, or zero for unsupported input.
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
196## @fn closes_same_line(line)
197## @brief Tests whether a recognized docstring closes on its opening line.
199## Identifies the governed opening width and searches the remainder of the line
200## for a second triple-double-quote delimiter.
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.
208## Nothing is read directly from STDIN.
210## Nothing is written to STDOUT.
212## Nothing is written to STDERR.
214## @returns One when a second delimiter occurs on the line; zero otherwise.
217 sub(/^[ \t]*/,
"", s)
219 if (width == 0)
return 0
220 rest = substr(s, width + 1)
221 return (index(rest,
"\"\"\"") > 0)
224## @fn translate_doc_line(line)
225## @brief Translates one supported structured field inside a docstring.
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.
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
239## @local exc Exception name extracted from a `:raises` field.
242## Nothing is read directly from STDIN.
244## Nothing is written directly to STDOUT.
246## Malformed governed fields are reported through `warn()`.
248## @returns Translated text, or original text when no safe translation exists.
251 sub(/[^ \t].*$/,
"", indent)
252 body = substr(line, length(indent) + 1)
253 if (body ~ /^:param[ \t]+[^:]+:/) {
255 sub(/^:param[ \t]+/,
"", name)
258 sub(/^[^:]*:[ \t]*/,
"", desc)
259 if (name ==
"" || name ~ /[ \t]/) {
warn(
"malformed :param field");
return line }
260 return indent
"@param " name (desc ==
"" ?
"" :
" " desc)
262 if (body ~ /^:param([ \t]|:|$)/) {
warn(
"malformed :param field");
return line }
263 if (body ~ /^:returns:[ \t]*/) {
265 sub(/^:returns:[ \t]*/,
"", desc)
266 if (desc ==
"") {
warn(
"malformed :returns field");
return line }
267 return indent
"@return " desc
269 if (body ~ /^:returns([ \t]|$)/) {
warn(
"malformed :returns field");
return line }
270 if (body ~ /^:raises[ \t]+[^:]+:/) {
272 sub(/^:raises[ \t]+/,
"", exc)
275 sub(/^[^:]*:[ \t]*/,
"", desc)
276 if (exc ==
"" || exc ~ /[ \t]/) {
warn(
"malformed :raises field");
return line }
277 return indent
"@exception " exc (desc ==
"" ?
"" :
" " desc)
279 if (body ~ /^:raises([ \t]|:|$)/) {
warn(
"malformed :raises field");
return line }
280 if (body ~ /^:yields:[ \t]*/) {
282 sub(/^:yields:[ \t]*/,
"", desc)
283 if (desc ==
"") {
warn(
"malformed :yields field");
return line }
284 return indent
"@par Yields\n" indent desc
286 if (body ~ /^:yields([ \t]|$)/) {
warn(
"malformed :yields field");
return line }
287 if (body ~ /^:type[ \t]+[^:]+:/) {
289 sub(/^:type[ \t]+/,
"", 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
296 if (body ~ /^:type([ \t]|:|$)/) {
warn(
"malformed :type field");
return line }
297 if (body ~ /^:rtype:[ \t]*/) {
299 sub(/^:rtype:[ \t]*/,
"", desc)
300 if (desc ==
"") {
warn(
"malformed :rtype field");
return line }
301 return indent
"@par Return type\n" indent desc
303 if (body ~ /^:rtype([ \t]|$)/) {
warn(
"malformed :rtype field");
return line }
307## @rule translate_source_record
308## @brief Passes source through and translates fields in recognized docstrings.
312 if (index(source_line,
"\"\"\"") > 0) { in_docstring = 0; print source_line; next }
316 if (in_declaration) {
320 pending_indent = declaration_indent
335 if (module_doc_possible) {
338 module_doc_possible = 0
349 pending_indent = declaration_indent
357## @rule finalize_filter
358## @brief Diagnoses unfinished state and enforces strict-mode failure.
360 if (in_docstring)
warn(
"unterminated recognized docstring")
361 if (strict && diagnostics > 0) exit 1
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.