2025-Q1: Source code markers design

[stanislaw]

I would like to discuss how we improve the user interface for source files and markers.

The inputs driving the change:

• Some identifiers can be pretty long. With the JUnit XML reports, we are getting UIDs that are pretty long.
• The work Support roles for file relations and markers #2104 will introduce source code marker roles. Which means we should ideally display the badges with UIDs and roles.
• We have backward source markers that are created from @relation(...) markers found in source code but we also have forward links from requirements that are done using RELATIONS / TYPE: File. Currently, the requirement marker does not show the backward/forward nature of a requirement.
• SPDX seems to be going in the direction of a different syntax where SPDX-... identifiers are key-valued in Doxygen comments. This convention and other possible conventions suggest that not much time should be spend on hardcoding the syntax highlighting to any specific marker syntax.

The second screenshot demonstrates where I am thinking this could go. All markers are stacked above the first line of the block where they are defined. This way it should be possible to also expand the requirements to see them in full (not just UIDs). Also, this top-to-bottom organization could help the requirements to visually "dominate" the implementation that follows just below.

Example: Requirement with a forward link to a function in source code

[REQUIREMENT]
UID: REQ-1
TITLE: Requirement Title
STATEMENT: Requirement Statement
RELATIONS:
- TYPE: File
  VALUE: file.c
  FUNCTION: hello_world
- TYPE: File
  VALUE: file.c
  FUNCTION: hello_world_2

Example: A branch where we just put together forward and backward markers

With this approach, the @relation markers are no longer highlighted.

Promising direction

Example: Experiment with counters

With this approach, the requirements identifiers are not visible by default but could be expanded on. It seems to hide the requirements too much.

[stanislaw]

We have released the version 0.8.0 where the screens look like this now. Closing this discussion as resolved.