Merge pull request #2547 from haxtibal/tdmg/exclude_empty_source_nodes

fix(backend/sdoc_source_code): Don't auto-generate sdoc nodes for function comments without fields

Author: stanislaw

strictdoc/core/file_traceability_index.py

@@ -647,6 +647,9 @@ def create_folder_section(
                 current_top_node = section_cache[path_component_]
 
             for source_node_ in traceability_info_.source_nodes:
+                if len(source_node_.fields) == 0:
+                    continue
+
                 assert source_node_.entity_name is not None
                 sdoc_node_uid = source_node_.get_sdoc_field(
                     "UID", relevant_source_node_entry

tests/integration/features/source_code_traceability/_source_nodes/11_functions_without_fields_do_not_generate_node/description.sdoc

@@ -0,0 +1,39 @@
+[DOCUMENT]
+MID: c2d4542d5f1741c88dfcb4f68ad7dcbd
+TITLE: Test specification
+UID: TEST_DOC
+
+[GRAMMAR]
+ELEMENTS:
+- TAG: SECTION
+  PROPERTIES:
+    IS_COMPOSITE: True
+  FIELDS:
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: True
+- TAG: TEST_SPEC
+  PROPERTIES:
+    VIEW_STYLE: Narrative
+  FIELDS:
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: True
+  - TITLE: INTENTION
+    TYPE: String
+    REQUIRED: False
+  - TITLE: INPUT
+    TYPE: String
+    REQUIRED: False
+  - TITLE: EXPECTED_RESULTS
+    TYPE: String
+    REQUIRED: False
+  RELATIONS:
+  - TYPE: Parent
+  - TYPE: File

tests/integration/features/source_code_traceability/_source_nodes/11_functions_without_fields_do_not_generate_node/input.sdoc

@@ -0,0 +1,12 @@
+[DOCUMENT]
+TITLE: Hello world doc
+
+[REQUIREMENT]
+UID: REQ-1
+TITLE: Requirement Title
+STATEMENT: Requirement Statement
+
+[REQUIREMENT]
+UID: REQ-2
+TITLE: Requirement Title #2
+STATEMENT: Requirement Statement #2

tests/integration/features/source_code_traceability/_source_nodes/11_functions_without_fields_do_not_generate_node/strictdoc.toml

@@ -0,0 +1,14 @@
+[project]
+
+features = [
+  "REQUIREMENT_TO_SOURCE_TRACEABILITY",
+  "SOURCE_FILE_LANGUAGE_PARSERS",
+]
+
+source_nodes = [
+  { "tests/" = { uid = "TEST_DOC", node_type = "TEST_SPEC" } }
+]
+
+exclude_source_paths = [
+    "test.itest"
+]

tests/integration/features/source_code_traceability/_source_nodes/11_functions_without_fields_do_not_generate_node/test.itest

@@ -0,0 +1,29 @@
+#
+# This test verifies that only functions that have at least one annotated field
+# get an auto-generated SDoc node, while plain comments without field annotation
+# don't cause auto-generation. Relation markers don't count as field annotation
+# and shall work as usual.
+#
+# @relation(SDOC-SRS-141, scope=file)
+#
+
+RUN: %strictdoc export %S --output-dir %T | filecheck %s
+
+CHECK: Published: Hello world doc
+
+RUN: %check_exists --file "%T/html/_source_files/tests/file.c.html"
+
+RUN: %cat %T/html/%THIS_TEST_FOLDER/input.html | filecheck %s --check-prefix CHECK-HTML
+CHECK-HTML: TEST_DOC/tests/file.c/test_case_1
+CHECK-HTML: tests/file.c, <i>lines: 3-20</i>, function test_case_1()
+# relation markers shall still work, but no link to auto-generated shall be there
+CHECK-HTML-NOT: TEST_DOC/tests/file.c/test_case_2
+CHECK-HTML: tests/file.c, <i>lines: 22-29</i>, function test_case_2()
+
+RUN: %cat %T/html/%THIS_TEST_FOLDER/description.html | filecheck %s --check-prefix CHECK-HTML-TESTSPEC
+CHECK-HTML-TESTSPEC: test_case_1
+CHECK-HTML-TESTSPEC-NOT: test_case_2
+
+# test_case_2 shall still count as covered, since it has a relation marker
+RUN: %cat %T/html/source_coverage.html | filecheck %s --check-prefix CHECK-SOURCE-COVERAGE
+CHECK-SOURCE-COVERAGE: 96.3

tests/integration/features/source_code_traceability/_source_nodes/11_functions_without_fields_do_not_generate_node/tests/file.c

@@ -0,0 +1,29 @@
+#include <stdio.h>
+
+/**
+ * Some text.
+ *
+ * @relation(REQ-1, scope=function)
+ *
+ * INTENTION: Intention...
+ *
+ * INPUT: This
+ *        is
+ *        a statement
+ *        \n\n
+ *        And this is the same statement's another paragraph.
+ *
+ * EXPECTED_RESULTS: This is a comment.
+ */
+void test_case_1(void) {
+    print("hello world\n");
+}
+
+/**
+ * Plain documentation, no fields. Don't auto-generate a SDoc node for this function.
+ *
+ * @relation(REQ-2, scope=function)
+ */
+void test_case_2(void) {
+    print("hello world\n");
+}