[FEAT-REQ] documentation for in-code requirements

[josecm]

We have code documentation guidelines using doxygen and requirement documentation, but we are missing the link between the two that will allow us to have full traceability.

The solution we previously discussed wat to add guidelines to use custom doxygen tags to link a given excerpt of code to one or many requirements.

[danielRep]

That solution for seems plausible. Should the requirement on the doxygen have a URL to the req plus the req ID ? Where should the link forward, bao-docs or bao-reqs?

[josecm]

I'm thinking only a req ID. Otherwise, the code will be too convoluted, and the URL can be broken.

[DavidMCerdeira]

If I correctly remember the previous conversations we've had about this, the idea was to generate a link with a custom tag that would should on the output documentation.

I think you're talking about having links in the doxygen comment directly.
From a usability standpoint I think it's worth it to keep the links up to date if they break. That said, I don't really like the idea of having URLs in the code, so having the links be generated based on the ID is a good middle ground.

[danielRep]

Yes, I agree with having links generated based on the ID. How should we start approaching this? What's the status on the bao-reqs @DavidMCerdeira ?

[DavidMCerdeira]

We need to finish all layers of requirements before mapping them to code.

1. Threats and assumptions
2. Objectives
3. High level requirements
4. Design level requirements
5. Implementation level requirements -> these are the ones that should be mapped to code using doxygen