Learn more about Real-Time Workshop Embedded Coder

Customizing Comments in Generated Code

On this page…
Adding Custom Comments to Generated Code Adding Global Comments

Adding Custom Comments to Generated Code

You can customize the comments in the generated code for ERT targets by setting or clearing several parameters on the Real-Time Workshop > Comments pane. These options let you enable or suppress generation of descriptive information in comments for blocks and other objects in the model.

To...	Select...
Include the text specified in the Description field of a block's Block Properties dialog box as comments in the code generated for each block	Simulink block descriptions.
Add a comment that includes the block name at the start of the code for each block	Simulink block descriptions
Include the text specified in the Description field of a Simulink data object (such as a signal, parameter, data type, or bus) in the Simulink Model Explorer as comments in the code generated for each object	Simulink data object descriptions.
Include comments just above signals and parameter identifiers in the generated code as specified in an M-code or TLC function.	Custom comments (MPT objects only).
Include the text specified in the Description field of the Properties dialog box for a Stateflow object as comments just above the code generated for each object	Stateflow object descriptions.
Include requirements assigned to Simulink blocks in the generated code comments (for more information, see Including Requirements Information with Generated Code in the Simulink Verification and Validation documentation)	Requirements in block comments.

When you select Simulink block descriptions,

• The description text for blocks and Stateflow objects and block names generated as comments can include international (non-US-ASCII) characters. (For details on international character support, see Support for International (Non-US-ASCII) Characters in the Real-Time Workshop documentation.)

• The Real-Time Workshop software automatically inserts comments into the generated code for custom blocks. Therefore, it is not necessary to include block comments in the associated TLC file for a custom block.

  Note   If you have existing TLC files with manually inserted comments for block descriptions, the code generation process emits these comments instead of the automatically generated comments. Consider removing existing block comments from your TLC files. Manually inserted comments might be poorly formatted in the generated code and code-to-model traceability might not work.

• For virtual blocks or blocks that have been removed due to block reduction, no comments are generated.

For more information, see Real-Time Workshop Pane: Comments in the Real-Time Workshop reference documentation.

Adding Custom Comments

This procedure allows you to add a comment just above a signal or parameter's identifier in the generated code. This is accomplished using

• A function that you write in M-code or TLC-code and save in a .m or .tlc file

• The Custom comments (MPT objects only) check box on the Comments pane of the Configuration Parameters dialog box

• Selecting the .m or .tlc file in the Custom comments function field on the Comments pane of the Configuration Parameters dialog box.

You may include at least some or all of the property values for the data object. Each Simulink data object (signal or parameter) has properties, as described in Parameter and Signal Property Values. This example comment contains some of the property values for the data object MAP as specified on the Model Explorer:

/*     DocUnits:       PSI                                  */
/*     Owner:                                               */
/*     DefinitionFile: specialDef                           */
real_T MAP = 0.0;

You can type text in the Description field on the Model Explorer for a signal or parameter data object. If you do, and if you select the Simulink data object descriptions check box on the Comments pane of the Configuration Parameters dialog box, this text will appear beside the signal's or parameter's identifier in the generated code as a comment. This is true whether or not you select the Custom comments (MPT objects only) check box discussed in this procedure. For example, typing Manifold Absolute Pressure in the Description field for the data object MAP always will result in the following in the generated code:

real_T MAP = 0.0;     /* Manifold Absolute Pressure */

1. Write a function in M-code or TLC-code that places comments in the generated files as desired. An example .m file named rtwdemo_comments_mptfun.m is provided in the matlab/toolbox/rtw/rtwdemos directory. This file contains instructions.

   The M-code function must have three arguments that correspond to objectName, modelName, and request, respectively. The TLC-code must have three arguments that correspond to objectRecord, modelName, and request, respectively. Note also, in the case of the TLC file, you can use the library function LibGetSLDataObjectInfo to get every property value of the data object.

2. Save the function as a .m file or a .tlc file with the desired filename and place it in any folder in the MATLAB path.

3. Open the model and the Configuration Parameters dialog box.

4. Click Comments under Real-Time Workshop on the left pane. The Comments pane appears on the right.

5. Select the Custom comments (MPT objects only) check box.

6. In the Custom comments function field, either type the filename of the .m file or .tlc file you created, or select this filename using the Browse button.

7. Click the Apply button.

8. Click Generate Code.

9. Open the generated files and inspect their content to ensure the comments are what you want.

Back to Top

Adding Global Comments

• Introduction

• Using a Simulink DocBlock to Add a Comment

• Using a Simulink Annotation to Add a Comment

• Using a Stateflow Note to Add a Comment

• Using Sorted Notes to Add Comments

Introduction

The procedures in this section explain how to add a global comment to a Simulink model so that the comment text appears in the generated file or files where desired. This is accomplished by specifying a template symbol name with a Simulink DocBlock, a Simulink annotation, or a Stateflow note, or by using a sorted-notes capability that works with Simulink annotations or Stateflow notes (but not DocBlocks). For more information about template symbols, see Template Symbols and Rules.

Note   Template symbol names Description and ModifiedHistory, referenced below, also are fields in the Model Properties dialog box. If you use one of these symbol names for global comment text, and its Model Properties field has text in it too, both will appear in the generated files.

Using a Simulink DocBlock to Add a Comment

1. With the model open, select Library Browser from the View menu.

2. Drag the DocBlock from Model-Wide Utilities in the Simulink library onto the model.

3. After double-clicking the DocBlock and typing the desired comment in the editor, save and close the editor. See DocBlock in the Simulink documentation for details.

4. Right-click the DocBlock and select Mask Parameters. The Block Parameters dialog box appears.

5. Type one of the following Documentation child into the RTW Embedded Coder Flag field, illustrated below, and then click OK: Abstract, Description, History, ModifiedHistory, or Notes. Template symbol names are case sensitive.

   

6. In the Block Properties dialog box, Block Annotation tab, select %<ECoderFlag> as shown in the figure below, and then click OK. The symbol name typed in the previous step now appears under the DocBlock on the model.

   

7. Save the model. After you generate code, the code generator places the comment in each generated file whose template has the symbol name you typed. The code generator places the comment in the generated file at the location that corresponds to where the symbol name is located in the template file.

8. To add one or more other comments to the generated files, repeat steps 1 through 7 as desired.

Using a Simulink Annotation to Add a Comment

1. Double-click the unoccupied area on the model where you want to place the comment. See Annotating Diagrams in the Simulink documentation for details.

   Note   If you want the code generator to sort multiple comments for the Notes symbol name, replace the next step with Using Sorted Notes to Add Comments.

2. Type <S:Symbol_name> followed by the comment, where Symbol_name is one of the following Documentation child : Abstract, Description, History, ModifiedHistory, or Notes. For example, type <S:Description>This is the description I want. Template symbol names are case sensitive. (The "S" before the colon indicates "symbol.")

3. Click outside the rectangle and save the model. After you generate code, the code generator places the comment in each generated file whose template has the symbol name you typed. The code generator places the comment in the generated file at the location that corresponds to where the symbol name is located in the template file.

4. To add one or more other comments to the generated files, repeat steps 1 through 3 as desired.

Using a Stateflow Note to Add a Comment

1. Right-click the desired unoccupied area on the Stateflow chart where you want to place the comment. See Using Notes to Extend Charts in the Stateflow documentation for details.

2. Select Add Note from the drop down menu.

   Note   If you want the code generator to sort multiple comments for the Notes symbol name, replace the next step with Using Sorted Notes to Add Comments.

3. Type <S:Symbol_name> followed by the comment, where Symbol_name is one of the following Documentation child : Abstract, Description, History, ModifiedHistory, or Notes. For example, type <S:Description>This is the description I want. Template symbol names are case sensitive.

4. Click outside the note and save the model. After you generate code, the code generator places the comment in each generated file whose template has the symbol name you typed. The code generator places the comment in the generated file at the location that corresponds to where the symbol name is located in the template file.

5. To add one or more other comments to the generated files, repeat steps 1 through 4 as desired.

Using Sorted Notes to Add Comments

The sorted-notes capability allows you to add automatically sorted comments to the generated files. The code generator places these comments in each generated file at the location that corresponds to where the Notes symbol is located in the template file.

The sorting order the code generator uses is

• Numbers before letters

• Among numbers, 0 is first

• Among letters, uppercase are before lowercase.

You can use sorted notes with a Simulink annotation or a Stateflow note, but not with a DocBlock:

• In the Simulink annotation or the Stateflow note, type <S:NoteY> followed by the first comment, where Y is a number or letter.

• Repeat for as many additional comments you want, except replace Y with a subsequent number or letter.

The figure below illustrates sorted notes on a model, and where the code generator places each in a generated file.

Here is the relevant fragment from the generated file for the above model:

** NOTES

** Note1: This is the first comment I want
associated with the Notes symbol.
Note2: This is the second comment I want under Notes.
Noteb: This is the third comment. 

**

Back to Top

Specifying Code Appearance and Documentation

Configuring the Appearance of Generated Identifiers

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS