chore: fix doxygen formatting

[vishwa2710]

Because of how our doxygen comments are formatted, they don't appear as tooltips with autocompletion in VSCode, nor when you hover over the functions etc.

Now, when we write code we can get these tool tips:

I used the following script to batch update all the files in the repo to follow the proper format.

import os
import glob
import re

# Get a list of all header files in the repository
header_files = glob.glob(os.path.join(".", "**/*.hpp"), recursive=True)

# Regular expression to match function definitions and their preceding docstrings
license_pattern = re.compile(r"\/{3} Apache.*", re.MULTILINE)
pattern = re.compile(r".*\/{3}.*", re.MULTILINE)
next_line_pattern = re.compile(r"^\s$")
extra_space_pattern = re.compile(r"\/{3}\s{18}")

for header_file in header_files:
    with open(header_file, "r") as file:
        content = file.readlines()

    # Process each line
    new_content = []
    skip_next_line = False
    for i in range(len(content)):
        if skip_next_line:
            skip_next_line = False
            continue

        line = content[i]

        if license_pattern.match(line):
            new_content.append(line)
            continue

        line = re.sub(r"@brief\s{,18}", "@brief ", line)
        line = re.sub(r"@param\s{,18}", "@param ", line)
        line = re.sub(r"\[in\] ", "", line)
        line = re.sub(r"@return\s{,18}", "@return ", line)
        line = re.sub(r"///\s{8}", "/// ", line)
        line = re.sub(r"@code", "@code{.cpp}", line)
        next_line = content[i + 1] if i + 1 < len(content) else ""

        # Check if the current and next line match the pattern
        if pattern.match(line) and next_line_pattern.match(next_line):
            new_content.append(
                line.rstrip() + "\n"
            )  # Remove trailing spaces and add one newline
            skip_next_line = (
                True  # Skip the next line as it is part of the matched pattern
            )
        else:
            new_content.append(line)

    # Write the modified content back to the file
    with open(header_file, "w") as file:
        file.writelines(new_content)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (bf8bd6d) 86.21% compared to head (7a00aa1) 86.21%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #289   +/-   ##
=======================================
  Coverage   86.21%   86.21%           
=======================================
  Files          74       74           
  Lines        6491     6491           
=======================================
  Hits         5596     5596           
  Misses        895      895           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Derollez]

Awesome! Let's merge and apply to other folders (sharing the load)?