Python module#

Overview#

cpp_comment_format.format(text[, style, ...])

Change formatting of comment blocks.

cpp_comment_format.Docstrings(text[, ...])

Class to format docstrings. From this class, one can loop over all docstrings in a file and format them. E.g.::.

cpp_comment_format.change_quotes(text, ...)

Change quotes used to quote text in all comment blocks. For example::.

cpp_comment_format.find_matching(text, ...)

Find matching 'brackets'.

Module#

class cpp_comment_format.Docstrings(text: str, opening: str = '/\\*\\*\\s*\n', closing: str = '\\*/', escape_input: bool = False)#

Class to format docstrings. From this class, one can loop over all docstrings in a file and format them. E.g.:

docstrings = Docstrings(code)

for i, doc in enumerate(docstrings):
    doc = ...
    docstrings[i] = doc

formatted_code = str(docstrings)
Parameters:

  • text – The source code.

  • opening – The opening symbol of the docstring (e.g. "/**").

  • closing – The closing symbol of the docstring (e.g. "/*").

  • escape_input – If True, escape the input string (e.g. "" becomes "\").

cpp_comment_format.change_quotes(text: str, search: str, replace: str, ignore_escaped: bool = True) → str#

Change quotes used to quote text in all comment blocks. For example:

"This is ``a`` variable."  ->  "This is `a` variable."
Parameters:

  • text – Source code.

  • search – The quote to search for, e.g. '.

  • replace – The quote to replace with, e.g. '.

  • ignore_escaped – Ignore escaped quotes (escaped with \).

Returns:

Source code with changed formatting.

cpp_comment_format.clang_format(text: str, executable: str = 'clang-format', style: dict = None) → str#

Format code blocks using clang-format.

Note:
The assumption is made that if any code block is formatted::

@code{.cpp} … @endcode

(i.e. the @code and @endcode are on separate lines).

Parameters:

  • text – Source code.

  • blocks – List of code blocks.

  • executable – Path to clang-format executable.

Returns:

Source code with formatted code blocks.

cpp_comment_format.cli_format(args: list[str])#

Command-line tool to print datasets from a file, see --help.

Parameters:

args – Command-line arguments (should be all strings).

cpp_comment_format.find_matching(text: str, opening: str, closing: str, escape_input: bool = True, ignore_escaped: bool = True) → dict#

Find matching ‘brackets’. Note that dangling closing ‘brackets’ are ignored. For this module this has the specific advantage that e.g. /* ... */ inside code blocks is ignored if /** ... */ is searched.

Parameters:

  • text – The string to consider.

  • opening – The opening bracket (e.g. "(", "[", "{").

  • closing – The closing bracket (e.g. ")", "]", "}").

  • escape_input – If True, escape the input string (e.g. "\" becomes "\\\").

  • ignore_escaped – Ignore escaped bracket (e.g. "\(", "\)", etc).

Returns:

Dictionary with {index_opening: index_closing}

cpp_comment_format.format(text: str, style: str = 'javadoc', doxygen: str = '@', tabsize: int = None, align_codeblock: bool = False) → str#

Change formatting of comment blocks. See doxygen.

Parameters:

  • style – Select style: "javadoc".

  • doxygen – Format doxygen commands with certain prefix ("@", "\"). False to skip.

  • tabsize – Specify tabsize.

  • align_codeblock – Align code blocks inside the comment blocks.

Returns:

Formatted text.