strictdoc-project · stanislaw · Nov 4, 2024 · Nov 4, 2024
diff --git a/docs/sphinx/source/strictdoc_01_user_guide.rst b/docs/sphinx/source/strictdoc_01_user_guide.rst
@@ -1783,9 +1783,13 @@ To connect a source file to a requirement, a dedicated ``@relation`` marker must
 
     For language-specific parsing of source code, e.g., Python and C, make sure to enable the corresponding option, see :ref:`Language-aware parsing of source code <SECTION-UG-Language-aware-parsing-of-source-code>`.
 
+.. warning::
+
+    The legacy ``@sdoc`` marker is still supported by StrictDoc but is deprecated. ``@relation`` is the new correct marker name.
+
 **1\) Linking a file to a requirement**
 
-The marker must be added to the top comment of a file. Currently supported only in Python.
+The marker must be added to the top comment of a file.
 
 .. code:: python
 

diff --git a/docs/sphinx/source/strictdoc_04_release_notes.rst b/docs/sphinx/source/strictdoc_04_release_notes.rst
@@ -3,6 +3,21 @@ $$$$$$$$$$$$$
 
 This document maintains a record of all changes to StrictDoc since November 2023. It serves as a user-friendly version of the changelog, complementing the automatically generated, commit-by-commit changelog available here: `StrictDoc Changelog <https://github.com/strictdoc-project/strictdoc/blob/main/CHANGELOG.md>`_.
 
+Unreleased 0.2.0 (2024-11-XX)
+=============================
+
+This release introduces several enhancements to the source code processing introduced in release 0.1.0.
+
+The backend now supports improved function tracing in C, Python, and general parsing code:
+
+- Forward ranges to C functions now include the top comment.
+- Each range type is displayed in the output HTML.
+- The C source code reader has been updated to support file-level scoping.
+- The source code reader now caches parsed objects to disk, improving reading performance.
+- Proper handling of functions inside nested Python classes has been implemented, allowing syntax like Foo.Bar.do_baz. Thanks to @haxtibal for contributing this enhancement.
+
+Additionally, caching has been centralized, and the cache directory is now configurable. The project configuration file now supports a ``cache_dir`` option, which can be set to values such as ``./output/build``. This setting can help make caching artifacts visible alongside documentation artifacts.
+
 0.1.0 (2024-11-01)
 ==================
 

diff --git a/docs/strictdoc_01_user_guide.sdoc b/docs/strictdoc_01_user_guide.sdoc
@@ -2125,9 +2125,13 @@ To connect a source file to a requirement, a dedicated ``@relation`` marker must
 
     For language-specific parsing of source code, e.g., Python and C, make sure to enable the corresponding option, see [LINK: SECTION-UG-Language-aware-parsing-of-source-code].
 
+.. warning::
+
+    The legacy ``@sdoc`` marker is still supported by StrictDoc but is deprecated. ``@relation`` is the new correct marker name.
+
 **1\) Linking a file to a requirement**
 
-The marker must be added to the top comment of a file. Currently supported only in Python.
+The marker must be added to the top comment of a file.
 
 .. code:: python
 

diff --git a/docs/strictdoc_04_release_notes.sdoc b/docs/strictdoc_04_release_notes.sdoc
@@ -6,6 +6,26 @@ STATEMENT: >>>
 This document maintains a record of all changes to StrictDoc since November 2023. It serves as a user-friendly version of the changelog, complementing the automatically generated, commit-by-commit changelog available here: `StrictDoc Changelog <https://github.com/strictdoc-project/strictdoc/blob/main/CHANGELOG.md>`_.
 <<<
 
+[SECTION]
+TITLE: Unreleased 0.2.0 (2024-11-XX)
+
+[TEXT]
+STATEMENT: >>>
+This release introduces several enhancements to the source code processing introduced in release 0.1.0.
+
+The backend now supports improved function tracing in C, Python, and general parsing code:
+
+- Forward ranges to C functions now include the top comment.
+- Each range type is displayed in the output HTML.
+- The C source code reader has been updated to support file-level scoping.
+- The source code reader now caches parsed objects to disk, improving reading performance.
+- Proper handling of functions inside nested Python classes has been implemented, allowing syntax like Foo.Bar.do_baz. Thanks to @haxtibal for contributing this enhancement.
+
+Additionally, caching has been centralized, and the cache directory is now configurable. The project configuration file now supports a ``cache_dir`` option, which can be set to values such as ``./output/build``. This setting can help make caching artifacts visible alongside documentation artifacts.
+<<<
+
+[/SECTION]
+
 [SECTION]
 TITLE: 0.1.0 (2024-11-01)
 

diff --git a/strictdoc/backend/sdoc_source_code/reader_c.py b/strictdoc/backend/sdoc_source_code/reader_c.py
@@ -57,7 +57,36 @@ def read(
 
         nodes = traverse_tree(tree)
         for node_ in nodes:
-            if node_.type == "function_definition":
+            if node_.type == "translation_unit":
+                if (
+                    len(node_.children) > 0
+                    and node_.children[0].type == "comment"
+                    and (comment_node := node_.children[0])
+                ):
+                    if comment_node.text is not None:
+                        comment_text = comment_node.text.decode("utf-8")
+                        markers = MarkerParser.parse(
+                            comment_text,
+                            node_.start_point[0] + 1,
+                            # It is important that +1 is not present here because
+                            # currently StrictDoc does not display the last empty line (\n is 10).
+                            node_.end_point[0]
+                            if input_buffer[-1] == 10
+                            else node_.end_point[0] + 1,
+                            node_.start_point[0] + 1,
+                            node_.start_point[1] + 1,
+                        )
+                        for marker_ in markers:
+                            if isinstance(marker_, FunctionRangeMarker) and (
+                                function_range_marker_ := marker_
+                            ):
+                                function_range_marker_processor(
+                                    function_range_marker_, parse_context
+                                )
+                                traceability_info.markers.append(
+                                    function_range_marker_
+                                )
+            elif node_.type == "function_definition":
                 function_name: str = ""
 
                 for child_ in node_.children:

diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/file.c b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/file.c
@@ -0,0 +1,11 @@
+/**
+ * Some text.
+ *
+ * @relation(REQ-1, scope=file)
+ * @relation(REQ-2, scope=file)
+ */
+#include <stdio.h>
+
+void hello_world(void) {
+    print("hello world\n");
+}
diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/input.sdoc b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/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
diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/strictdoc.toml b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/strictdoc.toml
@@ -0,0 +1,7 @@
+[project]
+
+features = [
+  "REQUIREMENT_TO_SOURCE_TRACEABILITY",
+  "SOURCE_FILE_LANGUAGE_PARSERS",
+  "PROJECT_STATISTICS_SCREEN"
+]
diff --git a/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/test.itest b/tests/integration/features/file_traceability/_language_parsers/c/04_c_file/test.itest
@@ -0,0 +1,30 @@
+REQUIRES: PYTHON_39_OR_HIGHER
+
+RUN: %strictdoc export %S --output-dir Output | filecheck %s --dump-input=fail
+CHECK: Published: Hello world doc
+
+RUN: %check_exists --file "%S/Output/html/_source_files/file.c.html"
+
+RUN: %cat %S/Output/html/%THIS_TEST_FOLDER/input.html | filecheck %s --dump-input=fail --check-prefix CHECK-HTML
+CHECK-HTML: <a{{.*}}href="../_source_files/file.c.html#REQ-1#1#11">
+CHECK-HTML: file.c, <i>lines: 1-11</i>, the whole file
+
+RUN: %cat %S/Output/html/_source_files/file.c.html | filecheck %s --dump-input=fail --check-prefix CHECK-SOURCE-FILE
+
+CHECK-SOURCE-FILE: href="../_source_files/file.c.html#REQ-1#1#11"
+CHECK-SOURCE-FILE: <b>[ 1-11 ]</b> file.c, the whole file
+
+CHECK-SOURCE-FILE: href="../_source_files/file.c.html#REQ-2#1#11"
+CHECK-SOURCE-FILE: <b>[ 1-11 ]</b> file.c, the whole file
+
+CHECK-SOURCE-FILE: <pre class="sdoc-comment"> * @relation(<a
+CHECK-SOURCE-FILE: class="pointer"
+CHECK-SOURCE-FILE: data-reqid="REQ-1"
+CHECK-SOURCE-FILE: data-begin="1"
+CHECK-SOURCE-FILE: data-end="11"
+CHECK-SOURCE-FILE: data-traceability-file-type="this_file"
+CHECK-SOURCE-FILE: href="../_source_files/file.c.html#REQ-1#1#11"
+CHECK-SOURCE-FILE: >REQ-1</a>, scope=file)</pre></div><div id="line-5" class="source__line-number"><pre>5</pre></div>
+
+RUN: %cat %S/Output/html/source_coverage.html | filecheck %s --dump-input=fail --check-prefix CHECK-SOURCE-COVERAGE
+CHECK-SOURCE-COVERAGE: 100.0%