feat(backend/sdoc_source_code): MarkerParser: preserve spaces when preprocessing code comments

strictdoc/backend/sdoc_source_code/helpers/comment_preprocessor.py

@@ -10,10 +10,11 @@
 
 def preprocess_source_code_comment(comment: str) -> str:
     """
-    Remove all Doxygen/Python/etc comment markers for processing.
+    Replace all Doxygen/Python/etc comment markers with spaces for easier processing.
 
-    FIXME: Maybe there is a more efficient way of doing this with no two
-           re.sub() calls.
+    Note that the replacement does not change the size of the input string. This is
+    important for the use case when StrictDoc writes the mutated code comments
+    back to source files.
     """
 
     def replace_with_spaces(match: Match[str]) -> str:
@@ -26,9 +27,4 @@ def replace_with_spaces(match: Match[str]) -> str:
         comment,
         flags=re.MULTILINE,
     )
-    return re.sub(
-        r"^[ \t]+$",
-        "",
-        replacement,
-        flags=re.MULTILINE,
-    )
+    return replacement

tests/unit/strictdoc/backend/sdoc_source_code/helpers/test_comment_preprocessor.py

@@ -6,6 +6,10 @@
 
 
 def test_001_doxygen_slashes_and_stars():
+    """
+    NOTE: The expected output contains invisible whitespaces.
+    """
+
     source_input = """\
 /**
  * @relation(REQ-1, scope=function)
@@ -17,14 +21,18 @@ def test_001_doxygen_slashes_and_stars():
     assert (
         preprocessed_comment
         == """\
-
+   
    @relation(REQ-1, scope=function)
-
+   
 """
     )
 
 
-def test_001_doxygen_three_slashes():
+def test_002_doxygen_three_slashes():
+    """
+    NOTE: The expected output contains invisible whitespaces.
+    """
+
     source_input = """\
 ///
 /// @relation(REQ-1, scope=function)
@@ -36,14 +44,18 @@ def test_001_doxygen_three_slashes():
     assert (
         preprocessed_comment
         == """\
-
+   
     @relation(REQ-1, scope=function)
-
+   
 """
     )
 
 
 def test_003_doxygen_two_slashes():
+    """
+    NOTE: The expected output contains invisible whitespaces.
+    """
+
     source_input = """\
 //
 // @relation(REQ-1, scope=function)
@@ -56,14 +68,18 @@ def test_003_doxygen_two_slashes():
     assert (
         preprocessed_comment
         == """\
-
+  
    @relation(REQ-1, scope=function)
-
+  
 """
     )
 
 
 def test_004_python():
+    """
+    NOTE: The expected output contains invisible whitespaces.
+    """
+
     source_input = """\
 #
 # @relation(REQ-1, scope=function)
@@ -75,8 +91,8 @@ def test_004_python():
     assert (
         preprocessed_comment
         == """\
-
+ 
   @relation(REQ-1, scope=function)
-
+ 
 """
     )