python-doxygen
Reference documentation for python-doxygen
Loading...
Searching...
No Matches
Functions
doxygen-python.awk File Reference

Translates supported Python docstring fields for Doxygen. More...

Go to the source code of this file.

Functions

static void awk_doxygen_begin_initialize_filter ()
 Initializes parser state and consumes the --strict option.
 
AwkValue leading_width (AwkValue line)
 Returns the leading indentation width of a source line.
 
AwkValue warn (AwkValue message)
 Records and emits one translation diagnostic.
 
AwkValue is_blank_or_comment (AwkValue line)
 Tests for input that may precede a suite's first statement.
 
AwkValue is_declaration_start (AwkValue line)
 Recognizes governed class and function declaration starts.
 
AwkValue declaration_header_complete (AwkValue line)
 Tests whether a declaration header reaches its suite-opening colon.
 
AwkValue starts_docstring (AwkValue line)
 Tests for a supported triple-double-quoted docstring start.
 
AwkValue docstring_open_width (AwkValue line)
 Returns the byte width of a supported docstring opening form.
 
AwkValue closes_same_line (AwkValue line)
 Tests whether a recognized docstring closes on its opening line.
 
AwkValue translate_doc_line (AwkValue line)
 Translates one supported structured field inside a docstring.
 
static void awk_doxygen_rule_translate_source_record ()
 Passes source through and translates fields in recognized docstrings.
 
static void awk_doxygen_end_finalize_filter ()
 Diagnoses unfinished state and enforces strict-mode failure.
 

Detailed Description

Translates supported Python docstring fields for Doxygen.

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.

Definition in file doxygen-python.awk.

Function Documentation

◆ closes_same_line()

AwkValue closes_same_line ( AwkValue  line)

Tests whether a recognized docstring closes on its opening line.

Identifies the governed opening width and searches the remainder of the line for a second triple-double-quote delimiter.

Parameters
lineRecognized docstring start line.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One when a second delimiter occurs on the line; zero otherwise.

◆ declaration_header_complete()

AwkValue declaration_header_complete ( AwkValue  line)

Tests whether a declaration header reaches its suite-opening colon.

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.

Parameters
linePhysical declaration-header line to inspect.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One when the last non-whitespace byte is a colon; zero otherwise.

◆ docstring_open_width()

AwkValue docstring_open_width ( AwkValue  line)

Returns the byte width of a supported docstring opening form.

Distinguishes ordinary and raw supported openings after removing leading horizontal whitespace. Unsupported forms return zero.

Parameters
lineSource line beginning with a possible docstring opening.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
Three for ordinary, four for raw, or zero for unsupported input.

◆ is_blank_or_comment()

AwkValue is_blank_or_comment ( AwkValue  line)

Tests for input that may precede a suite's first statement.

Removes leading horizontal whitespace from a scratch copy and then checks whether the remaining input is empty or begins with a comment marker.

Parameters
lineSource line to inspect.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One for blank or comment-only input; zero otherwise.

◆ is_declaration_start()

AwkValue is_declaration_start ( AwkValue  line)

Recognizes governed class and function declaration starts.

Removes leading horizontal whitespace from a scratch copy and recognizes only the conservative declaration-start forms governed by ADR-009.

Parameters
lineSource line to inspect.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One for a supported declaration start; zero otherwise.

◆ leading_width()

AwkValue leading_width ( AwkValue  line)

Returns the leading indentation width of a source line.

Copies the input into scratch storage before removing everything after the leading spaces and tabs. The caller-supplied value is not modified.

Parameters
lineSource line to inspect.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
Number of leading space and tab bytes.

◆ starts_docstring()

AwkValue starts_docstring ( AwkValue  line)

Tests for a supported triple-double-quoted docstring start.

Removes leading horizontal whitespace and recognizes the ordinary delimiter plus the r and R raw prefixes required by ADR-009.

Parameters
lineSource line to inspect.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One when the first non-whitespace bytes open a supported form.

◆ translate_doc_line()

AwkValue translate_doc_line ( AwkValue  line)

Translates one supported structured field inside a docstring.

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.

Parameters
linePhysical docstring line to inspect. field.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written directly to STDOUT.
STDERR
Malformed governed fields are reported through warn().
Returns
Translated text, or original text when no safe translation exists.

◆ warn()

AwkValue warn ( AwkValue  message)

Records and emits one translation diagnostic.

Increments the global diagnostic count and writes one location-qualified warning for the current input record.

Parameters
messageStable diagnostic text.
STDIN
Nothing is read directly from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Writes one warning containing the current file name and record number.
Side Effects
Increments the global diagnostics counter.
Returns
No meaningful value; callers use the function for its side effects.