Hello and welcome back to the Advent of SysML v2 – a daily, hands-on mini-course designed to bring you up to speed with the new SysML v2 standard and the modern Syside tooling that makes you productive from day one.

By the end of this lesson, you will:

• Learn the different kinds of comments you can use in your SysML models
• Learn how to specify an element in another language
• Generate other artifacts out of the model

If you want to dive deeper into the world of SysML v2, check out The SysML v2 Book, where this topic is also discussed in more detail.

Documentation

Although Model-Based Systems Engineering is obviously based on machine-readable models, we humans also like to read natural-language descriptions. Documentation is a key part of every engineering artifact. If we already have models, one of the best ways to store documentation is inside the model itself. In the second half of this lesson, you will learn how to extract this to generate actual documents.

We already used documentation comments in many of the previous lessons. They were the multi-line comments after the “doc” keyword. They always document the element in which they are nested. In the following example, we will explore some more features of doc comments.

As documentation can be written in many languages, one of the most important features of a doc comment is its locale. It specifies the language of the documentation text according to the ISO/IEC 15897 standard. Specifying it can help tools to apply correct spell-checking or select the doc comment for a specific language when generating or displaying documentation. You can see three doc comments with three different locales in lines 3, 8, and 13.

Even though it is possible to have multiple doc comments in a single element, it is good practice to set distinct names for them if there are more than one. This will help tools identify them when traversing the model. Accordingly, the doc comments in lines 8 and 13 have a name (we leave the “default” one unnamed).

One last thing you might have noticed is that the comment text has trailing stars on each line, as well as some indentation at the beginning of each line. KerML specifies how to process comments when extracting text. In short, the “/*” and “*/” are removed from the beginning and the end, just like the extra whitespace after/before them; and the indentation, the star, and the following (single) space character (if any) are also stripped from each middle line. As an example, the resulting text from the English doc comment is:

This version of Santa’s sleigh demonstrates how to specify elements in other languages.

Anything else is preserved, so the doc comment can contain an arbitrary markup language, such as HTML, as plain-text code.

Notes and Comments

Other than for documentation, we often like to leave comments in ur code or model. Their goal is usually to highlight or explain something to the reader of the model. SysML offers two ways for this in the textual notation.

Let’s start with notes. A note starts with a double slash (“//”) and ends at the end of the line, like the one in line 14 (or lines 3 and 16, for that matter, which we use to indicate that we do not show the full model here in the blog). The main thing you have to know about it is that it is not a model element. Once the textual notation is parsed into a model, there will be no trace of notes. You will see this when you traverse the model in the second half of the lesson.

Notes are useful to structure textual models. For example, we can add section headers to different parts of a declaration if it is too long. We can also explain things that are relevant only in the code. If you do not need to retrieve a piece of information from the model, for example, via the API or with Syside Automator, you can simply put it in a note.

Contrary to notes, comments do get stored in the model. Most of the time, you will see comments similar to the one in line 11, between “/*” and “*/” (similarly to doc comments, but without the “doc” keyword). This may confuse people who are familiar with programming languages because it is usually the same kind of animal as the one with the double slash, except it can be multi-line or end sooner than the line. Not in this case, though.

In its full form, a comment starts with the “comment” keyword, may have a name, a locale (just like doc comments), and can be about one or more specific elements listed after the “about” keyword. All these come before the actual comment text.

In line 5, we see the “comment” keyword and how to specify a locale. In this case, the comment keyword is actually optional, but it may be easier to read the model if the line starts with “comment” rather than “locale”.

In line 8, the comment has a name, and it is about the “greet” action usage. By default, comments are bout the element in which they are nested (like doc comments), but they can be attached to a different element with the “about” keyword. In this case, the declaration must start with the “comment” keyword (but the name is still optional).

When extracting the text of a comment, the same principles apply as for doc comments.

Textual Representation (aka. Language Annotation)

We have seen how to document something or leave comments in natural language. Sometimes, it can be useful to store the representation of a model element in another language. Not its documentation, but the element itself. This is what the textual representation annotation (also known informally as language annotation) allows.

In lines 9 and 10, we can see the simple form of a textual representation. It specifies the language in which the representation should be interpreted after the “language” keyword, and then the actual text is like a comment.

In the full form (line 12), a textual representation may also have a name, in which case the declaration starts with the “rep” keyword. In this case, we chose the Alf language, one of the three that is officially recognized in the SysML specification (besides “kerml” and “ocl”). The language can also be a natural language, which may be useful when defining requirements – coming soon in another episode.

Extracting Documentation with Syside Automator

Now that we’ve seen how to add documentation with locales to our models, let’s extract this information programmatically. This is particularly valuable for international teams that need to track translation coverage and generate documentation reports.

Accessing Documentation

Here’s how to iterate through a model and access documentation elements:

The documentation property returns all doc comments attached to an element. Each documentation object has a locale (which may be None for unspecified locales) and body containing the extracted text.

Checking Translation Coverage

For international projects, you might want to identify which elements are missing translations:

This immediately shows which elements need documentation or translation, which is essential for quality assurance and project management.

Exporting to CSV

Documentation can be exported to CSV for integration with other tools or for review workflows:

The resulting CSV can be opened in Excel, imported into requirements management tools, or processed by custom scripts, making your model documentation part of your broader engineering workflow.

Challenge for Tomorrow

Head over to Syside Cloud to access today’s challenge!

Using the L10_AnnotatedWorkshop.sysml model and the provided L10_extract_comments.py template script:

1. Use Syside Automator to extract comments from the model
2. Export the comments to CSV, similar to how documentation was extracted in this lesson
3. (Optional) Add more comments, in multiple locales, to the model to test your extraction script

The complete solution will be uploaded tomorrow.

Summary

In this episode, you learned about comments, documentation, and annotations in SysML v2. Comments add explanations without affecting model semantics. Documentation provides owned descriptions that can be extracted programmatically. Annotations, including textual representations, extend models flexibly for domain-specific needs and hybrid workflows.

These features make textual SysML v2 models self-explanatory and queryable – something that’s much harder to achieve with graphical-only approaches. Combined with Syside Cloud’s Automator and AI capabilities, they enable powerful automation and collaboration workflows.

If you haven’t yet done so, head to Syside Cloud to do the challenge. Don’t forget to come back tomorrow for another episode of the Advent of SysML v2!