Tracing Source Code

This guide explains how to use CodeLinks to trace source code files and lines to needs in your documentation.

Step 1: Install CodeLinks

Follow the installation instructions in the CodeLinks documentation.

Step 2: Configure CodeLinks

Add a [codelinks] section to your ubproject.toml (next to conf.py) with the following content:

Step 3: Add the src-trace Directive

In your documentation files, add the following directive to display traced source code links:

.. src-trace::
     :project: x-as-code-cpp
     :directory: .

Step 4: Annotate Your Source Code

Add comments to your source code files to link code lines to needs. For example, in src/main.cpp:

src/main.cpp

#include <iostream>

// @Adding two integers, IMPL_1, impl, [REQ_0815]
int add(int a, int b) {
    return a + b;
}

int main() {
  
    std::cout << "Hello World" << std::endl;

    return 0;
}

Step 5: View Traced Files and Lines

After following the steps above, the documentation will show the traced files and lines for each need in the specified project (x-as-code-cpp). Here we show only the implementation files (not test files):

Implementation: Adding two integers IMPL_1

remote-url: src/main.cpp#L3; links outgoing: REQ_0815

Implementation: Calculate Factorial IMPL_2

remote-url: src/sample1.cpp#L4; links incoming: T_FACT_001, T_FACT_002, T_FACT_003

Implementation: Check if prime IMPL_3

remote-url: src/sample1.cpp#L15; links incoming: T_PRIME_001, T_PRIME_002, T_PRIME_003

Implementation: Clone C string IMPL_4

remote-url: src/sample2.cpp#L7;

Implementation: Set C string IMPL_5

remote-url: src/sample2.cpp#L20;

Note: Test files are traced separately in the testing guide to avoid duplicate need IDs.

Summary

By following these steps, you can easily trace source code to requirements, improving traceability and documentation quality.

Advanced configuration options and features are available in the CodeLinks documentation.

Linking Requirements to Code

Finally you can link from/to the traced source code lines like this:

Requirement: Requirement linking to source code REQ_0815

status: open links incoming: IMPL_1

This is a requirement that links to a need that has traced source code lines.