pyfcstm.utils.doc

Multiline comment formatting utilities for extracted source documentation.

This module provides a single utility function used to clean and normalize multiline comments that are commonly extracted from source code by tools such as ANTLR4. It focuses on removing C-style comment delimiters, trimming unnecessary whitespace, and normalizing indentation to produce readable text.

The module contains the following main components:

format_multiline_comment() - Normalize and clean multiline comment text

Note

Line separators are normalized to '\n' when the UNITTEST environment variable is set, enabling deterministic behavior in test environments.

Example:

>>> raw = """/* Example
...  *  multiline comment
...  */"""
>>> format_multiline_comment(raw)
'Example\nmultiline comment'

format_multiline_comment

pyfcstm.utils.doc.format_multiline_comment(raw_doc: str) → str[source]

Format multiline comments parsed by ANTLR4 by removing comment markers and aligning indentation.

This function takes a raw multiline comment (including /* */ markers) and processes it to produce clean, properly formatted documentation text. It removes comment delimiters, trims unnecessary whitespace, and normalizes indentation.

Parameters:: raw_doc (str) – Raw comment text including /* */ markers
Returns:: Formatted comment text with markers removed and proper indentation
Return type:: str

Example:

>>> raw = """/* This is a
...  *  multiline comment
...  */"""
>>> format_multiline_comment(raw)
'This is a\nmultiline comment'