Merge pull request #2005 from strictdoc-project/stanislaw/source_code_cleanup

Code climate: backend/sdoc_source_code: rename parts -> functions

Author: stanislaw

strictdoc/backend/sdoc_source_code/grammar.py

@@ -1,6 +1,6 @@
 SOURCE_FILE_GRAMMAR = """
 SourceFileTraceabilityInfo[noskipws]:
-  parts += Part
+  g_parts += Part
 ;
 
 Part[noskipws]:

strictdoc/backend/sdoc_source_code/models/function.py

@@ -15,14 +15,16 @@ def __init__(
         name: str,
         line_begin: int,
         line_end: int,
-        parts: List[Any],
+        child_functions: List[Any],
         markers: List[FunctionRangeMarker],
         attributes: Set[FunctionAttribute],
     ):
         assert parent is not None
         self.parent = parent
         self.name = name
-        self.parts: List[Any] = parts
+        # Child functions are supported in programming languages that can nest
+        # functions, for example, Python.
+        self.child_functions: List[Function] = child_functions
         self.markers: List[FunctionRangeMarker] = markers
         self.line_begin = line_begin
         self.line_end = line_end

strictdoc/backend/sdoc_source_code/models/source_file_info.py

@@ -15,15 +15,15 @@
 
 @auto_described
 class SourceFileTraceabilityInfo:
-    def __init__(self, parts: List):
+    def __init__(self, g_parts: List):
         """
         At the init time, only the backward RangeMarkers are available from
         a source file. At runtime, the ForwardRangeMarkers are mixed in
         from the Requirement/FileReference links. This is why the .markers
         is a union.
         """
 
-        self.parts: List = parts
+        self.g_parts: List = g_parts
         self.functions: List[Function] = []
 
         """

strictdoc/backend/sdoc_source_code/reader_c.py

@@ -152,9 +152,6 @@ def read(
                             traceability_info.markers.append(
                                 function_range_marker_
                             )
-                            traceability_info.parts.append(
-                                function_range_marker_
-                            )
                             function_markers.append(marker_)
 
                 # The function range includes the top comment if it exists.
@@ -165,7 +162,7 @@ def read(
                     if function_comment_node is not None
                     else node_.range.start_point[0] + 1,
                     line_end=node_.range.end_point[0] + 1,
-                    parts=[],
+                    child_functions=[],
                     markers=function_markers,
                     attributes=function_attributes,
                 )
@@ -215,9 +212,6 @@ def read(
                             traceability_info.markers.append(
                                 function_range_marker_
                             )
-                            traceability_info.parts.append(
-                                function_range_marker_
-                            )
                             function_markers.append(marker_)
 
                 # The function range includes the top comment if it exists.
@@ -228,7 +222,7 @@ def read(
                     if function_comment_node is not None
                     else node_.range.start_point[0] + 1,
                     line_end=node_.range.end_point[0] + 1,
-                    parts=[],
+                    child_functions=[],
                     markers=function_markers,
                     attributes={FunctionAttribute.DEFINITION},
                 )
@@ -260,12 +254,10 @@ def read(
                         range_marker_ := marker_
                     ):
                         range_marker_processor(range_marker_, parse_context)
-                        traceability_info.parts.append(range_marker_)
                     elif isinstance(marker_, LineMarker) and (
                         line_marker_ := marker_
                     ):
                         line_marker_processor(line_marker_, parse_context)
-                        traceability_info.parts.append(line_marker_)
                     else:
                         continue
             else:

strictdoc/backend/sdoc_source_code/reader_python.py

@@ -66,7 +66,7 @@ def read(
                     name="module",
                     line_begin=node_.start_point[0] + 1,
                     line_end=node_.end_point[0] + 1,
-                    parts=[],
+                    child_functions=[],
                     markers=[],
                     attributes=set(),
                 )
@@ -189,7 +189,7 @@ def read(
                     name=function_name,
                     line_begin=node_.range.start_point[0] + 1,
                     line_end=node_.range.end_point[0] + 1,
-                    parts=[],
+                    child_functions=[],
                     # Python functions do not need to track markers.
                     markers=[],
                     attributes=set(),
@@ -198,7 +198,7 @@ def read(
 
                 parent_function = functions_stack[-1]
 
-                parent_function.parts.append(new_function)
+                parent_function.child_functions.append(new_function)
                 functions_stack.append(new_function)
                 traceability_info.functions.append(new_function)
             elif node_.type == "comment":
@@ -236,8 +236,6 @@ def read(
             or functions_stack[0].name == "translation_unit"
         )
 
-        traceability_info.parts = functions_stack[0].parts
-
         source_file_traceability_info_processor(
             traceability_info, parse_context
         )

tests/unit/strictdoc/backend/sdoc_source_code/test_dsl_source_file_syntax.py

@@ -214,7 +214,7 @@ def test_010_nosdoc_keyword():
     reader = SourceFileTraceabilityReader()
 
     document = reader.read(source_input)
-    assert len(document.parts) == 7
+    assert len(document.g_parts) == 7
     assert len(document.markers) == 0
 
 
@@ -237,7 +237,7 @@ def test_011_nosdoc_keyword_then_normal_marker():
     reader = SourceFileTraceabilityReader()
 
     document = reader.read(source_input)
-    assert len(document.parts) == 12
+    assert len(document.g_parts) == 12
     assert len(document.markers) == 2
 
 
@@ -260,7 +260,7 @@ def test_011_nosdoc_keyword_then_normal_marker_4spaces_indent():
     reader = SourceFileTraceabilityReader()
 
     document = reader.read(source_input)
-    assert len(document.parts) == 12
+    assert len(document.g_parts) == 12
     assert len(document.markers) == 2
 
 

tests/unit/strictdoc/backend/sdoc_source_code/test_dsl_source_file_syntax_c.py

@@ -38,7 +38,7 @@ def test_01_single_string():
     info = reader.read(input_string)
 
     assert isinstance(info, SourceFileTraceabilityInfo)
-    assert len(info.parts) == 0
+    assert len(info.functions) == 0
     assert len(info.markers) == 0
 
 
@@ -72,7 +72,6 @@ def test_02_functions():
     )
 
     assert isinstance(info, SourceFileTraceabilityInfo)
-    assert len(info.parts) == 2
     assert len(info.markers) == 2
     assert info.markers[0].ng_source_line_begin == 3
     assert info.markers[0].ng_range_line_begin == 3

tests/unit/strictdoc/backend/sdoc_source_code/test_dsl_source_file_syntax_python.py

@@ -39,7 +39,7 @@ def test_01_single_string():
     info = reader.read(input_string)
 
     assert isinstance(info, SourceFileTraceabilityInfo)
-    assert len(info.parts) == 0
+    assert len(info.functions) == 0
     assert len(info.markers) == 0
 
 
@@ -79,52 +79,52 @@ def hello_3_1_1():
     info: SourceFileTraceabilityInfo = reader.read(input_string)
 
     assert isinstance(info, SourceFileTraceabilityInfo)
-    assert len(info.parts) == 3
+    assert len(info.functions) == 9
 
-    function_1 = info.parts[0]
+    function_1 = info.functions[0]
     assert isinstance(function_1, Function)
     assert function_1.name == "hello_1"
-    assert len(function_1.parts) == 1
+    assert len(function_1.child_functions) == 1
 
-    function_1_1 = function_1.parts[0]
+    function_1_1 = function_1.child_functions[0]
     assert isinstance(function_1_1, Function)
     assert function_1_1.name == "hello_1_1"
-    assert len(function_1_1.parts) == 1
+    assert len(function_1_1.child_functions) == 1
 
-    function_1_1_1 = function_1_1.parts[0]
+    function_1_1_1 = function_1_1.child_functions[0]
     assert isinstance(function_1_1_1, Function)
     assert function_1_1_1.name == "hello_1_1_1"
-    assert len(function_1_1_1.parts) == 0
+    assert len(function_1_1_1.child_functions) == 0
 
-    function_2 = info.parts[1]
+    function_2 = info.functions[3]
     assert isinstance(function_2, Function)
     assert function_2.name == "hello_2"
-    assert len(function_2.parts) == 1
+    assert len(function_2.child_functions) == 1
 
-    function_2_1 = function_2.parts[0]
+    function_2_1 = function_2.child_functions[0]
     assert isinstance(function_2_1, Function)
     assert function_2_1.name == "hello_2_1"
-    assert len(function_2_1.parts) == 1
+    assert len(function_2_1.child_functions) == 1
 
-    function_2_1_1 = function_2_1.parts[0]
+    function_2_1_1 = function_2_1.child_functions[0]
     assert isinstance(function_2_1_1, Function)
     assert function_2_1_1.name == "hello_2_1_1"
-    assert len(function_2_1_1.parts) == 0
+    assert len(function_2_1_1.child_functions) == 0
 
-    function_3 = info.parts[2]
+    function_3 = info.functions[6]
     assert isinstance(function_3, Function)
     assert function_3.name == "hello_3"
-    assert len(function_3.parts) == 1
+    assert len(function_3.child_functions) == 1
 
-    function_3_1 = function_3.parts[0]
+    function_3_1 = function_3.child_functions[0]
     assert isinstance(function_3_1, Function)
     assert function_3_1.name == "hello_3_1"
-    assert len(function_3_1.parts) == 1
+    assert len(function_3_1.child_functions) == 1
 
-    function_3_1_1 = function_3_1.parts[0]
+    function_3_1_1 = function_3_1.child_functions[0]
     assert isinstance(function_3_1_1, Function)
     assert function_3_1_1.name == "hello_3_1_1"
-    assert len(function_3_1_1.parts) == 0
+    assert len(function_3_1_1.child_functions) == 0
 
 
 def test_001_one_range_marker():