[2447] Escape the block comment terminator when exporting a comment body

[kkkk1258999]

PLEASE READ ALL ITEMS AND CHECK ONLY RELEVANT CHECKBOXES BELOW

Auto review

• Have you reviewed this PR? Please do a first quick review, It is very useful to detect typos and missing copyrights, check comments, check your code... The reviewer will thank you for that :)

Project management

• Has the pull request been added to the relevant milestone?
• Have the priority: and pr: labels been added to the pull request? (In case of doubt, start with the labels priority: low and pr: to review later)
• Have the relevant issues been added to the pull request?
• Have the relevant labels been added to the issues? (area:, type:)
• Have the relevant issues been added to the same project milestone as the pull request?

Changelog and release notes

• Has the CHANGELOG.adoc + doc/content/modules/user-manual/pages/release-notes/YYYY.MM.0.adoc been updated to reference the relevant issues?
• Have the relevant API breaks been described in the CHANGELOG.adoc?
• Are the new / upgraded dependencies mentioned in the relevant section of the CHANGELOG.adoc?
• In case of a change with a visual impact, are there any screenshots in the doc/content/modules/user-manual/pages/release-notes/YYYY.MM.0.adoc?
• In case of a key change, has the change been added to Key highlights section in doc/content/modules/user-manual/pages/release-notes/YYYY.MM.0.adoc?

Documentation

• Have you included an update of the documentation in your pull request? Please ask yourself if an update (installation manual, user manual, developer manual...) is needed and add one accordingly.

Tests

• Is the code properly tested? Any pull request (fix, enhancement or new feature) should come with a test (or several). It could be unit tests, integration tests or cypress tests depending on the context. Only doc and releng pull request do not need for tests.

---

The unchecked boxes of the Project management section are the ones I have no
permission for: the milestone and the labels, on this pull request and on the
issue. Could someone from the team set them? The remaining unchecked boxes do
not apply: there is no API break, no dependency change, and no visual impact
since this only changes the exported text.

Fixes #2447

Problem

getCommentBody concatenated the body between /* and */ without any
escaping, so a body containing the terminator closed the comment early and the
rest of it was exported as if it were SysML v2 code:

doc /* Closing a block comment looks like */ in the code */

The comment ends at the first terminator, in the code is left as code and the
trailing one is dangling, so the exported file does not parse. Documenting a
piece of code is enough to run into it.

Fix

The grammar defines a comment as

REGULAR_COMMENT: /\*[\s\S]*?\*/

a non greedy match up to the first terminator, with no escape sequence and no
nesting, so that sequence cannot be represented inside a comment body. It is
separated by a space instead:

doc /* Closing a block comment looks like * / in the code */

Since the exported text is then not exactly the one that was written, it is
reported as a warning through the existing report consumer rather than changed
silently. The export was silently broken before, and a silent rewrite would
only move the surprise somewhere else.

The reverse replacement is deliberately not done on import: a body may
legitimately contain the separated form, and turning it back would corrupt it.

getCommentBody is used for the body of a Comment, of a Documentation and
of a TextualRepresentation, so all three are covered by the single change.

Tests

SysMLElementSerializerTest.documentationContainingACommentTerminator exports
a documentation whose body contains the terminator, and checks both the
separated form in the output and the reported warning.

The 124 existing tests of SysMLElementSerializerTest and the 47 tests of
ImportExportTests still pass.

Note

This came out of #2436, where the documentation widget of the Details view is
to be replaced by the RichTextEditor. It is not specific to rich text though,
the defect is there today, which is why it is fixed separately and does not
wait for the SiriusWeb release.