Link MATLAB Code to Requirements

You can associate requirements with MATLAB^® code and plain-text external code, such as C code, by creating selection-based links with the Requirements Editor or by creating links programmatically at the MATLAB command line. You can also create links to MATLAB code in MATLAB Function (Simulink) blocks. You can then view and edit links to code in the MATLAB Editor or Requirements Editor.

Create Links to MATLAB Code or Plain-Text External Code

You can create links to MATLAB code or plain-text external code programmatically or by using the Requirements Editor.

When you create links to code, Requirements Toolbox™ creates slreq.TextRange objects that correspond to the selected lines. These slreq.TextRange objects are referred to as line ranges.

To create links programmatically, create the slreq.TextRange object, then use the object as a link source when you create the link. When you create multiple slreq.TextRange objects in the same MATLAB code file or plain-text external code file, the line numbers for the slreq.TextRange objects cannot overlap.

Create Links by Using the Requirements Editor

To create selection-based links to code by using the Requirements Editor:

In the MATLAB Editor, open the MATLAB code file or plain-text external code file.

Note
You cannot create links to MATLAB code in MLX files.
Select the lines of code that you want to link.
In the Requirements Editor, load the requirement set that you want to link.
Select the requirement to link.
In the Links section, click Add Link > Link from Selection in MATLAB Editor.
Alternatively, in the MATLAB Editor, right-click the selected code range and select Requirements > Link to Selection in Requirements Browser.

Create Links Programmatically

Suppose that you want to programmatically create links to a MATLAB function called myAdd.

function y = myAdd(u,v)
y = u + v;
end

You want to link the function to these requirements:

Requirements for the myAdd function, including requirements for the inputs, outputs, and function behavior.

To create links at the MATLAB command line:

Use slreq.createTextRange to create an slreq.TextRange object that represents the lines of code that you want to link to.
```
lr = slreq.createTextRange("myAdd.m",2);
```
Use slreq.find, find, or slreq.getCurrentObject to get a handle to the requirement that you want to link.
```
req = slreq.find(Type="Requirement",Summary="Add u and v");
```
Use slreq.createLink to create the link.
```
myLink = slreq.createLink(lr,req);
```

Create Links to MATLAB Function Blocks

Use the MATLAB Function Block Editor (Simulink) to create links to lines of code in MATLAB Function blocks:

In the Requirements Editor, load the requirement set that you want to link to.
Select the requirement to link.
In the Simulink^® model, open the MATLAB Function block.
Select the lines of code that you want to link.
Right-click the selected code range and select Requirements > Link to Selection in Requirements Browser.

Note

Requirements linked to MATLAB code lines inside a MATLAB Function block appear in HTML requirements traceability reports, but do not appear the Simulink Report Generator™ Web View. See Create and Use Web Views of Models (Simulink Report Generator).

Create Links to Requirements in External Documents

To create links from MATLAB code to requirements in external documents:

Select a requirement in one of these external documents:
- Microsoft^® Word
- Microsoft Excel^®
- IBM^® DOORS^®
- IBM DOORS Next
In the MATLAB Editor, open the MATLAB code file or plain-text external code file.

Note
You cannot create links to MATLAB code in MLX files.
Select the lines of code that you want to link.
Right-click the selected code range and select Requirements. Depending on the type of your requirements document, select one of these options:
- Link to Selection in Word
- Link to Selection in Excel
- Link to Selection in DOORS
- Link to Selected Item(s) in DOORS Next

For more information about configuring Requirements Toolbox to work with these third-party products, see Configure Requirements Toolbox for Interaction with Microsoft Office and IBM DOORS and Configure IBM DOORS Next Session.

View and Edit Links and Linked Line Ranges

You can view linked code ranges in the MATLAB Editor by enabling requirements highlighting. Right-click in the MATLAB Editor and select Requirements > Enable Requirements Highlighting.

To edit links, use the Requirements Editor. For more information, see View and Edit Links.

You can also edit the starting and ending lines for a linked line range in the MATLAB Editor or at the MATLAB command line.

Edit Linked Line Ranges in the MATLAB Editor

To edit the line numbers for a linked line range in the MATLAB Editor:

Right-click a highlighted line range and select Requirements > Adjust line range.
In the Adjust range dialog box, use the + and - buttons to change the first and last lines of the line range. Alternatively, enter the line number in the field.
Click OK. The MATLAB Editor updates the highlighting.

Edit Linked Line Ranges Programmatically

To edit the lines for an slreq.TextRange object at the MATLAB command line:

Open the MATLAB code file or plain-text external code file in the MATLAB Editor.
```
open("myAdd.m");
```
Get the existing slreq.TextRange object in the MATLAB code file by passing the file name and the line numbers for the start and end of the line range to the slreq.getTextRange function.
```
lr = slreq.getTextRange("myAdd.m",[1 2]);
```
Modify the line range by using setLineRange.
```
setLineRange(lr,1);
```
The MATLAB Editor updates the code range highlighting. Alternatively, you can confirm the changes by using show, getText, or getLineRange.

Save Links

To save the changes to a link set when you create or edit links to lines of MATLAB code or external code, use one of these approaches:

In the MATLAB Editor, right-click and select Requirements > Save Links.
In the Requirements Editor, click Show Links. Select the link set, and click Save.
At the MATLAB command line, use save.

Delete Links and Unused Line Ranges

You can delete links to MATLAB code in the MATLAB Editor, the Requirements Editor, or at the MATLAB command line.

If you delete links to code ranges in the MATLAB Editor, you can delete the unused line ranges in the MATLAB Editor or at the MATLAB command line.

Delete Links

To delete links in the MATLAB Editor, right-click a highlighted code range and select Requirements > Delete All Links. This deletes all incoming and outgoing links to this code range.

To delete links from the Requirements Editor, see Delete Links and Link Sets.

To delete links at the MATLAB command line, get a handle to an slreq.Link object and use remove. Alternatively, ensure that the file containing the code range is open in the MATLAB Editor, then get an slreq.TextRange object by using slreq.getTextRange. Delete the links to the object by using deleteLinks.

Delete Unused Line Ranges

To delete unused line ranges in the MATLAB Editor, right-click the line containing the line range and select Requirements > Delete line range.

Note

If a line range does not have outgoing links, the MATLAB Editor does not highlight the code line. Note the line number before you delete the link so that you can delete the unused line range. Alternatively, you can use the MATLAB command line to get the line ranges in a file and then delete the unused line ranges.

To delete line ranges at the command line, ensure that the file containing the code range is open in the MATLAB Editor, then get an slreq.TextRange object by using slreq.getTextRange. Delete the code range by using remove.

Repair Links

Links from line ranges may become unresolved if modifications to the MATLAB code or plain-text file result in a deleted line range or a range that cannot be located. To view unresolved links, in the Requirements Editor, click Show Links. Unresolved links display the unresolved link icon . You can delete unresolved links if they are no longer needed or use the setSource method to repair the links. For more information on unresolved links and how to repair the links, see Resolve Links.