Annotations

An annotating element is used to provide additional information about annotated elements. There are several kinds of annotating elements:

• comment is used to provide textual descriptions about other elements. Comments may be about the namespace that owns them, or they may be about different elements, in which case they must be specified.
• documentation is a kind of comment used to document the annotated element. Documentation comments always annotate a single element, which is their owning element.
• textual representation is an annotating element whose textual body provides a representation of the annotated element in a specifically named language (such as SysML textual notation). As for documentation, a textual representation is always owned by its represented element.

The annotated elements can own annotating elements, related via the owning membership relationship. The comment and textual representation elements can also be related to the annotated elements via the annotation relationship. In symbolic views, you can create or display the annotation and owning membership relationships using the Display Others command between the annotating and annotated elements, which can be represented either as element symbols or compartment elements. The documentation element is always related via the owning membership, however, if it is documenting an element other than its owner, the relationship is represented in a view as an annotation.

For a line note in the Textual Editor, see the Managing Textual Editor page.

Creating comments

Creating comments via the Textual Editor

To create comments via the Textual Editor

1. In the Textual Editor, place the cursor where you want to create the element and do one of the following: 
   1. For an unnamed and/or unspecified comment, use symbols /* and */ with the comment text in between.
   2. For a named and/or specified comment, declare the keyword comment, specify its name (optional), then the keyword about followed by the name of the element it annotates (optional), specify the keyword locale followed by the language of the body text and the region and/or encoding, then symbols /* and */ with the comment text in between.
2. Click the Synchronize button.

Creating comments via the Create Element command

To create comments via the Create Element command

1. Right-click an element, and in the shortcut menu, click Create Element.

2. In the Create Element dialog, click comment.
3. Specify the comment text.
4. (Optional) Specify the commented element.

Creating comments via the view palette

To create comments via the view palette

1. In the view palette, under the Common group, click the comment button.
2. Click in the view pane where you want to create the comment symbol.
3. Specify the comment text.
4. (Optional) Specify the commented element.

Specifying the commented element

Specifying the commented element via the Textual Editor

If the comment is an owned member of a namespace, then the explicit identification of annotated elements can be omitted, in which case the annotated element is implicitly the containing namespace. 

To specify the commented element explicitly, use the about syntax. See the procedure Creating comments via the Textual Editor.

Specifying the commented element via the view palette

To specify the commented element via the view palette

1. In the view palette, under the Other Relationships group, click the annotation button.
2. In the view pane, click on the comment element, then the element you want to annotate with the comment.
   The annotation relationship is created and the element is annotated with the comment.

Specifying the commented element via the Create Relationship command

To specify the commented element via the Create Relationship command

1. Right-click the comment element.
2. In the shortcut menu, click Create Relationship, then in the submenu, click Outgoing, and then in the submenu, click annotation. The Element Picker dialog opens.
3. In the Element Picker dialog, do one of the following:
   1. In a view, click the element symbol you want to annotate. Hold Shift to select multiple elements. 
   2. Click the Add button. The element selection dialog opens. In the element selection dialog, select the element you want to annotate and click OK.
   3. Drag and drop the needed element you want to annotate from the Containment tree onto the Element Picker.
4. In the Element Picker dialog, click OK. 

Creating documentation

Creating documentation via the Textual Editor

To create documentation via the Textual Editor

1. In the Textual Editor, place the cursor where you want to create the element and declare the keyword doc, then specify the name (optional), followed by symbols /* and */ with the documentation text in between.   
2. Click the Synchronize button.
   

   part tank {
       doc /* tank is full */
   }

Creating documentation via the Create Element command

To create documentation via the Create Element command

1. In the Containment tree, right-click an element for which you want to create documentation, and in the shortcut menu, click Create Element.

2. In the Create Element dialog, click documentation.
3. Specify the documentation text.

Creating documentation via the view palette

To create documentation via the view palette

1. In the view palette, under the Common group, click the documentation button.
2. Click in the view pane where you want to create the documentation symbol.
3. Specify the documentation text.

Creating documentation via the Specification panel

To create documentation via the Specification panel

• See the procedure Modifying the documentation of the element via the Specification panel on the Specification panel page.

Creating textual representation

Creating textual representation via the Textual Editor

To create textual representation via the Textual Editor

1. In the Textual Editor, place the cursor where you want to create the element and declare the keyword rep, then specify the name (optional), then the keyword language with the language specified as a literal string, followed by symbols /* and */ with the documentation text in between.
   
   

   If the textual representation element has no name, the keyword rep can be omitted.

2. Click the Synchronize button.