pyfcstm 0.0.1__py3-none-any.whl

pyfcstm/render/__init__.py

@@ -0,0 +1,3 @@
+from .env import create_env
+from .expr import render_expr_node, fn_expr_render, create_expr_render_template
+from .render import StateMachineCodeRenderer

pyfcstm/render/env.py

@@ -0,0 +1,36 @@
+"""
+Jinja2 Environment Module
+
+This module provides functionality for creating and configuring a Jinja2 environment
+for template rendering. It sets up global variables and adds custom settings to the
+environment to support state machine template rendering.
+"""
+
+import jinja2
+
+from ..dsl import INIT_STATE, EXIT_STATE
+from ..utils import add_settings_for_env
+
+
+def create_env():
+    """
+    Create and configure a Jinja2 environment for template rendering.
+
+    This function initializes a Jinja2 Environment instance, adds custom settings
+    through the add_settings_for_env utility, and sets up global variables for
+    state machine templates including initial and exit states.
+
+    :return: A configured Jinja2 Environment instance
+    :rtype: jinja2.Environment
+
+    Example::
+
+        >>> env = create_env()
+        >>> template = env.from_string("Initial state: {{ INIT_STATE }}")
+        >>> rendered = template.render()
+    """
+    env = jinja2.Environment()
+    env = add_settings_for_env(env)
+    env.globals['INIT_STATE'] = INIT_STATE
+    env.globals['EXIT_STATE'] = EXIT_STATE
+    return env

pyfcstm/render/expr.py

@@ -0,0 +1,180 @@
+"""
+Expression rendering module for converting DSL nodes to different language formats.
+
+This module provides functionality to render expression nodes in various language styles
+including DSL, C/C++, and Python. It uses Jinja2 templating to transform abstract syntax
+tree nodes into string representations according to the specified language style.
+
+The module contains predefined templates for different node types and operators,
+and allows for custom template extensions.
+"""
+
+from functools import partial
+from typing import Optional, Dict, Union, Any
+
+import jinja2
+
+from .env import create_env
+from ..dsl import node as dsl_nodes
+from ..model import Integer, Float, Boolean
+
+_DSL_STYLE = {
+    'Float': '{{ node.value | repr }}',
+    'Integer': '{{ node.value | repr }}',
+    'Boolean': '{{ node.value | repr }}',
+    'Constant': '{{ node.value | repr }}',
+    'HexInt': '{{ node.value | hex }}',
+    'Paren': '({{ node.expr | expr_render }})',
+    'UFunc': '{{ node.func }}({{ node.expr | expr_render }})',
+    'Name': '{{ node.name }}',
+    'UnaryOp': '{{ node.op }}{{ node.expr | expr_render }}',
+    'BinaryOp': '{{ node.expr1 | expr_render }} {{ node.op }} {{ node.expr2 | expr_render }}',
+    'ConditionalOp': '({{ node.cond | expr_render }}) ? {{ node.value_true | expr_render }} : {{ node.value_false | expr_render }}',
+}
+
+_C_STYLE = {
+    **_DSL_STYLE,
+    'Boolean': '{{ (1 if node.value else 0) | hex }}',
+    'BinaryOp(**)': 'pow({{ node.expr1 | expr_render }}, {{ node.expr2 | expr_render }})',
+}
+
+_PY_STYLE = {
+    **_DSL_STYLE,
+    'UFunc': 'math.{{ node.func }}({{ node.expr | expr_render }})',
+    'UnaryOp(!)': 'not {{ node.expr | expr_render }}',
+    'BinaryOp(&&)': '{{ node.expr1 | expr_render }} and {{ node.expr2 | expr_render }}',
+    'BinaryOp(||)': '{{ node.expr1 | expr_render }} or {{ node.expr2 | expr_render }}',
+    'ConditionalOp': '{{ node.value_true | expr_render }} if {{ node.cond | expr_render }} else {{ node.value_false | expr_render }}',
+}
+
+_KNOWN_STYLES = {
+    'dsl': _DSL_STYLE,
+    'c': _C_STYLE,
+    'cpp': _C_STYLE,
+    'python': _PY_STYLE,
+}
+
+
+def fn_expr_render(node: Union[float, int, dict, dsl_nodes.Expr, Any], templates: Dict[str, str],
+                   env: jinja2.Environment):
+    """
+    Render an expression node using the provided templates and Jinja2 environment.
+
+    This function handles different types of expression nodes and selects the appropriate
+    template for rendering based on the node type and available templates.
+
+    :param node: The expression node to render, can be a DSL node or a primitive value
+    :type node: Union[float, int, dict, dsl_nodes.Expr, Any]
+
+    :param templates: Dictionary mapping node types to Jinja2 template strings
+    :type templates: Dict[str, str]
+
+    :param env: Jinja2 environment for template rendering
+    :type env: jinja2.Environment
+
+    :return: The rendered string representation of the expression node
+    :rtype: str
+
+    Example::
+
+        >>> env = create_env()
+        >>> templates = _DSL_STYLE
+        >>> fn_expr_render(Integer(42).to_ast_node(), templates, env)
+        '42'
+    """
+    if isinstance(node, dsl_nodes.Expr):
+        if isinstance(node, (dsl_nodes.Float, dsl_nodes.Integer, dsl_nodes.Boolean, dsl_nodes.Constant,
+                             dsl_nodes.HexInt, dsl_nodes.Paren, dsl_nodes.Name, dsl_nodes.ConditionalOp)) \
+                and type(node).__name__ in templates:
+            template_str = templates[type(node).__name__]
+        elif isinstance(node, dsl_nodes.UFunc) and f'{type(node).__name__}({node.func})' in templates:
+            template_str = templates[f'{type(node).__name__}({node.func})']
+        elif isinstance(node, dsl_nodes.UFunc) and type(node).__name__ in templates:
+            template_str = templates[type(node).__name__]
+        elif isinstance(node, dsl_nodes.UnaryOp) and f'{type(node).__name__}({node.op})' in templates:
+            template_str = templates[f'{type(node).__name__}({node.op})']
+        elif isinstance(node, dsl_nodes.UnaryOp) and type(node).__name__ in templates:
+            template_str = templates[type(node).__name__]
+        elif isinstance(node, dsl_nodes.BinaryOp) and f'{type(node).__name__}({node.op})' in templates:
+            template_str = templates[f'{type(node).__name__}({node.op})']
+        elif isinstance(node, dsl_nodes.BinaryOp) and type(node).__name__ in templates:
+            template_str = templates[type(node).__name__]
+        else:
+            template_str = templates['default']
+
+        tp: jinja2.Template = env.from_string(template_str)
+        return tp.render(node=node)
+
+    elif isinstance(node, bool):
+        return fn_expr_render(Boolean(node).to_ast_node(), templates=templates, env=env)
+    elif isinstance(node, int):
+        return fn_expr_render(Integer(node).to_ast_node(), templates=templates, env=env)
+    elif isinstance(node, float):
+        return fn_expr_render(Float(node).to_ast_node(), templates=templates, env=env)
+    else:
+        return repr(node)
+
+
+def create_expr_render_template(lang_style: str = 'dsl', ext_configs: Optional[Dict[str, str]] = None):
+    """
+    Create a template dictionary for expression rendering based on the specified language style.
+
+    This function combines the predefined templates for the specified language style with
+    any additional custom templates provided in ext_configs.
+
+    :param lang_style: The language style to use ('dsl', 'c', 'cpp', 'python')
+    :type lang_style: str
+
+    :param ext_configs: Optional additional template configurations to extend or override defaults
+    :type ext_configs: Optional[Dict[str, str]]
+
+    :return: A dictionary of templates for the specified language style
+    :rtype: Dict[str, str]
+
+    Example::
+
+        >>> templates = create_expr_render_template('python', {'CustomNode': '{{ node.custom_value }}'})
+        >>> 'UFunc' in templates and 'CustomNode' in templates
+        True
+    """
+    return {**_KNOWN_STYLES[lang_style], **(ext_configs or {})}
+
+
+def render_expr_node(expr: Union[float, int, dict, dsl_nodes.Expr, Any],
+                     lang_style: str = 'dsl', ext_configs: Optional[Dict[str, str]] = None,
+                     env: Optional[jinja2.Environment] = None):
+    """
+    Render an expression node to a string representation in the specified language style.
+
+    This is a high-level function that sets up the environment and renders the expression
+    in one step. It's a convenient wrapper around add_expr_render_to_env and fn_expr_render.
+
+    :param expr: The expression to render
+    :type expr: Union[float, int, dict, dsl_nodes.Expr, Any]
+
+    :param lang_style: The language style to use ('dsl', 'c', 'cpp', 'python')
+    :type lang_style: str
+
+    :param ext_configs: Optional additional template configurations
+    :type ext_configs: Optional[Dict[str, str]]
+
+    :param env: Optional pre-configured Jinja2 environment
+    :type env: Optional[jinja2.Environment]
+
+    :return: The rendered string representation of the expression
+    :rtype: str
+
+    Example::
+
+        >>> from pyfcstm.dsl import Integer
+        >>> render_expr_node(Integer('42'), lang_style='python')
+        '42'
+        >>> render_expr_node(Integer('42'), lang_style='c')
+        '42'
+    """
+    env = env or create_env()
+    templates = create_expr_render_template(lang_style, ext_configs)
+    _fn_expr_render = partial(fn_expr_render, templates=templates, env=env)
+    env.globals['expr_render'] = _fn_expr_render
+    env.filters['expr_render'] = _fn_expr_render
+    return _fn_expr_render(node=expr)

pyfcstm/render/func.py

@@ -0,0 +1,77 @@
+"""
+Module for processing items to objects with Jinja2 templates and dynamic imports.
+
+This module provides functionality to convert dictionary configurations into callable objects,
+templates, or imported objects based on their specified type. It supports creating template
+renderers, importing objects from modules, and extracting values from configuration dictionaries.
+"""
+
+import jinja2
+from hbutils.reflection import quick_import_object
+
+
+def process_item_to_object(f, env: jinja2.Environment):
+    """
+    Process a configuration item into an object based on its type.
+
+    This function converts dictionary configurations into different types of objects:
+
+    - 'template': Creates a callable template renderer function
+    - 'import': Imports an object from a specified module
+    - 'value': Extracts a value from the configuration
+    - For other types or non-dictionary inputs, returns the input unchanged
+
+    :param f: The configuration item to process, can be a dictionary or any other type
+    :type f: dict or any
+
+    :param env: The Jinja2 environment used for template rendering
+    :type env: jinja2.Environment
+
+    :return: The processed object (function, imported object, value, or unchanged input)
+    :rtype: any
+
+    Example::
+
+        >>> env = jinja2.Environment()
+        >>> # Create a template renderer
+        >>> template_config = {'type': 'template', 'template': 'Hello {{ name }}', 'params': ['name']}
+        >>> renderer = process_item_to_object(template_config, env)
+        >>> renderer('World')
+        'Hello World'
+
+        >>> # Import an object
+        >>> import_config = {'type': 'import', 'from': 'math.sqrt'}
+        >>> sqrt_fn = process_item_to_object(import_config, env)
+        >>> sqrt_fn(16)
+        4.0
+    """
+    if isinstance(f, dict):
+        type_ = f.pop('type', None)
+        if type_ == 'template':
+            params = f.pop('params', None)
+            template = f.pop('template')
+            if params is not None:  # with params order
+                obj_template = env.from_string(template)
+
+                def _fn_render(*args, **kwargs):
+                    render_args = dict(zip(params, args))
+                    return obj_template.render(**render_args, **kwargs)
+
+                return _fn_render
+
+            else:  # no params order
+                return env.from_string(template).render
+
+        elif type_ == 'import':
+            from_ = f.pop('from')
+            obj, _, _ = quick_import_object(from_)
+            return obj
+
+        elif type_ == 'value':
+            value = f.pop('value')
+            return value
+
+        else:
+            return f
+    else:
+        return f

pyfcstm/render/render.py

@@ -0,0 +1,279 @@
+"""
+State Machine Code Renderer Module
+
+This module provides functionality for rendering state machine models into code using templates.
+It uses Jinja2 templating engine to transform state machine models into various programming
+languages and formats based on template configurations.
+
+Template Directory Structure:
+    The template directory should contain:
+
+    - ``config.yaml``: Configuration file for the renderer
+    - ``*.j2`` files: Jinja2 templates that will be rendered
+    - Other files: Will be copied directly to the output directory
+
+Configuration File (config.yaml) Structure:
+    - ``expr_styles``: Dictionary defining expression rendering styles
+      - ``default``: Default style configuration (will use 'dsl' as base_lang if not specified)
+
+      - ``[style_name]``: Additional named styles
+        - base_lang: Base language style ('dsl', 'c', 'cpp', 'python')
+        - [additional options]: Extra rendering options for the style
+    - ``globals``: Dictionary of global variables to be added to the Jinja2 environment
+      Each entry can be:
+
+      - ``type: template``: A template renderer function
+        - params: List[str], means the parameter list of this template rendering function, e.g. ``['a', 'b']``.
+        - template: str, means the Jinja2-format text render template, e.g. ``{{ a + b * 2 }}``.
+      - ``type: import``: An imported object
+        - from: str, means the import position, e.g. `math.sin`.
+      - ``type: value``: A direct value
+        - value: Any, means any possible value, e.g. ``1``, ``'Hello World'``.
+      - Other values (e.g. ``1``, ``'Hello World'``) means directly this value itself.
+
+    - ``filters``: Dictionary of filter functions to be added to the Jinja2 environment
+      (Same format as globals)
+
+    - ``tests``: Dictionary of test functions to be added to the Jinja2 environment
+      (Same format as globals)
+
+    - ``ignores``: List of file patterns to ignore (using gitignore syntax, e.g. ``.git``, ``*.md``, etc)
+
+Expression Rendering:
+    The expr_styles configuration allows customizing how expressions are rendered in different
+    language styles. The base_lang determines the starting template set, which can be extended
+    or overridden with additional configuration.
+
+    And you can use these pre-defined styles in ``expr_render`` function/filter in the template.
+    When use ``{{ expression | expr_render }}`` it will use ``default`` style to render your expression.
+    When use ``{{ expression | expr_render(style='c') }}`` it will use ``c`` style to render your expression.
+
+"""
+import copy
+import os.path
+import pathlib
+import shutil
+import warnings
+from functools import partial
+from typing import Dict, Callable, Union, Any
+
+import pathspec
+import yaml
+
+from .env import create_env
+from .expr import create_expr_render_template, fn_expr_render, _KNOWN_STYLES
+from .func import process_item_to_object
+from ..dsl import node as dsl_nodes
+from ..model import StateMachine
+
+
+class StateMachineCodeRenderer:
+    """
+    Renderer for generating code from state machine models using templates.
+
+    This class handles the rendering of state machine models into code using
+    Jinja2 templates. It supports custom expression styles, global functions,
+    filters, and tests through a configuration file.
+
+    :param template_dir: Directory containing the templates and configuration
+    :type template_dir: str
+
+    :param config_file: Name of the configuration file within the template directory
+    :type config_file: str, default: 'config.yaml'
+    """
+
+    def __init__(self, template_dir: str, config_file: str = 'config.yaml'):
+        """
+        Initialize the StateMachineCodeRenderer.
+
+        :param template_dir: Directory containing the templates and configuration
+        :type template_dir: str
+
+        :param config_file: Name of the configuration file within the template directory
+        :type config_file: str, default: 'config.yaml'
+        """
+        self.template_dir = os.path.abspath(template_dir)
+        self.config_file = os.path.join(self.template_dir, config_file)
+
+        self.env = create_env()
+        self._ignore_patterns = ['.git']
+        self._prepare_for_configs()
+
+        self._path_spec = pathspec.PathSpec.from_lines(
+            pathspec.patterns.GitWildMatchPattern, self._ignore_patterns
+        )
+
+        self._file_mappings: Dict[str, Callable] = {}
+        self._prepare_for_file_mapping()
+
+    def _prepare_for_configs(self):
+        """
+        Load and process the configuration file.
+
+        This method reads the configuration file, sets up expression rendering styles,
+        and registers globals, filters, and tests in the Jinja2 environment.
+
+        :raises FileNotFoundError: If the configuration file does not exist
+        :raises yaml.YAMLError: If the configuration file contains invalid YAML
+        """
+        with open(self.config_file, 'r') as f:
+            config_info = yaml.safe_load(f)
+
+        expr_styles = config_info.pop('expr_styles', None) or {}
+        expr_styles['default'] = expr_styles.get('default') or {'base_lang': 'dsl'}
+        d_templates = copy.deepcopy(_KNOWN_STYLES)
+        for style_name, expr_style in expr_styles.items():
+            lang_style = expr_style.pop('base_lang')
+            d_templates[style_name] = create_expr_render_template(
+                lang_style=lang_style,
+                ext_configs=expr_style,
+            )
+
+        def _fn_expr_render(node: Union[float, int, dict, dsl_nodes.Expr, Any], style: str = 'default'):
+            """
+            Render an expression node using the specified style.
+
+            :param node: The expression node to render
+            :type node: Union[float, int, dict, dsl_nodes.Expr, Any]
+
+            :param style: The expression rendering style to use
+            :type style: str, default: 'default'
+
+            :return: The rendered expression as a string
+            :rtype: str
+            """
+            return fn_expr_render(
+                node=node,
+                templates=d_templates[style],
+                env=self.env,
+            )
+
+        self.env.globals['expr_render'] = _fn_expr_render
+        self.env.filters['expr_render'] = _fn_expr_render
+
+        globals_ = config_info.pop('globals', None) or {}
+        for name, value in globals_.items():
+            self.env.globals[name] = process_item_to_object(value, env=self.env)
+        filters_ = config_info.pop('filters', None) or {}
+        for name, value in filters_.items():
+            self.env.filters[name] = process_item_to_object(value, env=self.env)
+        tests = config_info.pop('tests', None) or {}
+        for name, value in tests.items():
+            self.env.tests[name] = process_item_to_object(value, env=self.env)
+
+        ignores = list(config_info.pop('ignores', None) or [])
+        self._ignore_patterns.extend(ignores)
+
+    def _prepare_for_file_mapping(self):
+        """
+        Prepare file mappings for rendering or copying.
+
+        This method walks through the template directory and creates mappings for:
+        - .j2 files: Will be rendered using Jinja2
+        - Other files: Will be copied directly to the output directory
+
+        Files matching the ignore patterns will be excluded.
+        """
+        for root, _, files in os.walk(self.template_dir):
+            for file in files:
+                _, ext = os.path.splitext(file)
+                current_file = os.path.abspath(os.path.join(root, file))
+                rel_file = os.path.relpath(current_file, self.template_dir)
+                if self._path_spec.match_file(rel_file):
+                    continue
+                if ext == '.j2':
+                    rel_file = os.path.splitext(rel_file)[0]
+                    self._file_mappings[rel_file] = partial(
+                        self.render_one_file,
+                        template_file=current_file,
+                    )
+                elif not os.path.samefile(current_file, self.config_file):
+                    self._file_mappings[rel_file] = partial(
+                        self.copy_one_file,
+                        src_file=current_file,
+                    )
+
+    def render_one_file(self, model: StateMachine, output_file: str, template_file: str):
+        """
+        Render a single template file.
+
+        :param model: The state machine model to render
+        :type model: StateMachine
+
+        :param output_file: Path to the output file
+        :type output_file: str
+
+        :param template_file: Path to the template file
+        :type template_file: str
+
+        :raises jinja2.exceptions.TemplateError: If there's an error in the template
+        :raises IOError: If there's an error reading or writing files
+        """
+        tp = self.env.from_string(pathlib.Path(template_file).read_text())
+        if os.path.dirname(output_file):
+            os.makedirs(os.path.dirname(self.config_file), exist_ok=True)
+        os.makedirs(os.path.dirname(output_file), exist_ok=True)
+        with open(output_file, 'w') as f:
+            f.write(tp.render(model=model))
+
+    def copy_one_file(self, model: StateMachine, output_file: str, src_file: str):
+        """
+        Copy a single file to the output directory.
+
+        :param model: The state machine model (unused in this method)
+        :type model: StateMachine
+
+        :param output_file: Path to the output file
+        :type output_file: str
+
+        :param src_file: Path to the source file
+        :type src_file: str
+
+        :raises IOError: If there's an error copying the file
+        """
+        _ = model
+        if os.path.dirname(output_file):
+            os.makedirs(os.path.dirname(self.config_file), exist_ok=True)
+        shutil.copyfile(src_file, output_file)
+
+    def render(self, model: StateMachine, output_dir: str, clear_previous_directory: bool = False):
+        """
+        Render the state machine model to the output directory.
+
+        This method processes all template files and copies all other files
+        from the template directory to the output directory according to the
+        configured mappings.
+
+        :param model: The state machine model to render
+        :type model: StateMachine
+
+        :param output_dir: Directory where the rendered files will be placed
+        :type output_dir: str
+
+        :param clear_previous_directory: Whether to clear the output directory before rendering
+        :type clear_previous_directory: bool, default: False
+
+        :raises IOError: If there's an error accessing or writing to the output directory
+
+        Example::
+
+            >>> renderer = StateMachineCodeRenderer('./templates')
+            >>> renderer.render(my_state_machine, './output', clear_previous_directory=True)
+        """
+        output_dir = os.path.abspath(output_dir)
+        os.makedirs(output_dir, exist_ok=True)
+        if clear_previous_directory:
+            for file in os.listdir(output_dir):
+                dst_file = os.path.join(output_dir, file)
+                if os.path.isfile(dst_file):
+                    os.remove(dst_file)
+                elif os.path.isdir(dst_file):
+                    shutil.rmtree(dst_file)
+                elif os.path.islink(dst_file):
+                    os.unlink(dst_file)
+                else:
+                    warnings.warn(f'Unable to clean file {dst_file!r}.')  # pragma: no cover
+
+        for rel_file, fn_op in self._file_mappings.items():
+            dst_file = os.path.join(output_dir, rel_file)
+            fn_op(model=model, output_file=dst_file)

pyfcstm/utils/__init__.py

@@ -0,0 +1,6 @@
+from .binary import is_binary_file
+from .doc import format_multiline_comment
+from .jinja2 import add_builtins_to_env, add_settings_for_env
+from .json import IJsonOp
+from .text import normalize, to_identifier
+from .validate import ValidationError, ModelValidationError, IValidatable

pyfcstm/utils/binary.py

@@ -0,0 +1,38 @@
+"""
+This module provides functionality to determine whether a given file is a binary file or a text file.
+It does so by reading the first 1024 bytes of the file and checking for the presence of non-text characters.
+
+.. note::
+    Inspired from https://stackoverflow.com/a/7392391/6995899
+"""
+
+_TEXT_CHARS = bytearray({7, 8, 9, 10, 12, 13, 27} | set(range(0x20, 0x100)) - {0x7f})
+
+
+def is_binary_file(file) -> bool:
+    """
+    Check if a given file is binary.
+
+    This function reads the first 1024 bytes of the file and checks if it contains any
+    non-text (binary) characters. It uses a predefined set of text characters to determine
+    the nature of the file.
+
+    :param file: The path to the file to be checked.
+    :type file: str
+
+    :return: True if the file is binary, False if it is a text file.
+    :rtype: bool
+
+    :raises FileNotFoundError: If the specified file does not exist.
+    :raises IOError: If there is an error reading the file.
+
+    :example:
+
+    >>> is_binary_file('example.txt')
+    False
+    >>> is_binary_file('example.bin')
+    True
+    """
+    with open(file, 'rb') as f:
+        prefix = f.read(1024)
+        return bool(prefix.translate(None, _TEXT_CHARS))

pyfcstm/utils/doc.py

@@ -0,0 +1,64 @@
+"""
+Provides functionality for formatting multiline comments in code.
+
+This module contains utilities for cleaning and formatting multiline comments
+that have been parsed from source code, particularly those extracted by ANTLR4.
+It handles removing comment markers, aligning indentation, and cleaning up
+whitespace to produce readable documentation text.
+"""
+
+import os
+import re
+import textwrap
+
+
+def format_multiline_comment(raw_doc):
+    """
+    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.
+
+    :param raw_doc: Raw comment text including /* */ markers
+    :type raw_doc: str
+
+    :return: Formatted comment text with markers removed and proper indentation
+    :rtype: str
+
+    Example::
+
+        >>> raw = \"\"\"/* This is a
+        ...  *  multiline comment
+        ...  */\"\"\"
+        >>> format_multiline_comment(raw)
+        'This is a\\nmultiline comment'
+    """
+    if re.fullmatch(r'\s*/\*+/\s*', raw_doc.strip()):
+        return ""
+
+    # Use regex to remove opening comment markers (/* with one or more asterisks)
+    content = re.sub(r'^\s*/\*+', '', raw_doc.strip())
+
+    # Use regex to remove closing comment markers
+    content = re.sub(r'\*+/\s*$', '', content)
+
+    # Split into lines
+    lines = content.splitlines()
+
+    i = 0
+    while i < len(lines) and not lines[i].strip():
+        i += 1
+    lines = lines[i:]
+
+    i = len(lines) - 1
+    while i > 0 and not lines[i].strip():
+        i -= 1
+    lines = lines[:i + 1]
+
+    # Use textwrap.dedent to align indentation
+    formatted_text = textwrap.dedent(os.linesep.join(map(str.rstrip, lines)))
+
+    return formatted_text