[6243] Add documentation in the new representation modal by gdaniel · Pull Request #6245 · eclipse-sirius/sirius-web

gdaniel · 2026-03-03T17:13:52Z

Bug: #6243

Pull request template

General purpose

What is the main goal of this pull request?

Project management

Has the pull request been added to the relevant project and milestone? (Only if you know that your work is part of a specific iteration such as the current one)
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:, difficulty:, type:)
Have the relevant issues been added to the same project and milestone as the pull request?
Has the CHANGELOG.adoc been updated to reference the relevant issues?
Have the relevant API breaks been described in the CHANGELOG.adoc? (Including changes in the GraphQL API)
In case of a change with a visual impact, are there any screenshots in the CHANGELOG.adoc? For example in doc/screenshots/2022.5.0-my-new-feature.png

Architectural decision records (ADR)

Does the title of the commit contributing the ADR start with [doc]?
Are the ADRs mentioned in the relevant section of the CHANGELOG.adoc?

Dependencies

Are the new / upgraded dependencies mentioned in the relevant section of the CHANGELOG.adoc?
Are the new dependencies justified in the CHANGELOG.adoc?

Frontend

This section is not relevant if your contribution does not come with changes to the frontend.

General purpose

Is the code properly tested? (Plain old JavaScript tests for business code and tests based on React Testing Library for the components)

Typing

We need to improve the typing of our code, as such, we require every contribution to come with proper TypeScript typing for both changes contributing new files and those modifying existing files.
Please ensure that the following statements are true for each file created or modified (this may require you to improve code outside of your contribution).

Backend

This section is not relevant if your contribution does not come with changes to the backend.

General purpose

Are all the event handlers tested?
Are the event processor tested?
Is the business code (services) tested?
Are diagram layout changes tested?

Architecture

Are data structure classes properly separated from behavioral classes?
Are all the relevant fields final?
Is any data structure mutable? If so, please write a comment indicating why
Are behavioral classes either stateless or side effect free?

Review

How to test this PR?

Please describe here the various use cases to test this pull request

Has the Kiwi TCMS test suite been updated with tests for this contribution?

gdaniel · 2026-03-03T17:27:39Z

...ench-views/explorer/context-menu-contributions/new-representation/NewRepresentationModal.tsx

            />
-            <InputLabel id="newRepresentationModalRepresentationDescriptionLabel">{t('type.label')}</InputLabel>
-            <Select
+            <TextField


I used this PR as an excuse to uniformize the rendering of input labels in this modal. See below the before/after comparison.
Note that I aligned the font on the smaller label (name), which makes the difference between the helper text and the label a bit difficult to distinguish. Let me know if I should change that.

The label of the field should not look like the helper text of the previous field. It should be bigger. Have a look at the label / helper text in the new project page for example.

Ok, I'll do the same thing as in the duplicate object dialog then

Done, for the record, this is how it looks like, let me know if you want me to change it

gdaniel · 2026-03-03T17:28:43Z

...va/org/eclipse/sirius/components/collaborative/dto/RepresentationDescriptionMetadataDTO.java

+ *
+ * @author arichard
+ */
+public record RepresentationDescriptionMetadataDTO(String id, String label, String defaultName, String description) {


As discussed, I renamed this class to RepresentationDescriptionMetadataDTO (and moved it to the DTO package).
Note that I also transformed the class into a record.

sbegaudeau · 2026-03-04T09:26:36Z

...main/java/org/eclipse/sirius/components/view/emf/ViewRepresentationDescriptionsProvider.java

        if (viewRepresentationDescription.isPresent()) {
            String defaultName = viewRepresentationDescription.map(view -> this.getDefaultName(view, editingContext, object)).orElse(representationDescription.getLabel());
-            result.add(new RepresentationDescriptionMetadata(representationDescription.getId(), representationDescription.getLabel(), defaultName));
+            String documentation = viewRepresentationDescription.map(RepresentationDescription::getDescription).orElse("");


I don't think that this will have the content you imagine. The field RepresentationDescription#description in the View DSL will contain some sort of internal description of the representation. Think of it as multiple paragraphs of content similar to a Javadoc. This will not have some short documentation for the end user. It has not been exposed to the frontend on purpose.

In Sirius Desktop, there are both:

https://github.com/eclipse-sirius/sirius-desktop/blob/master/plugins/org.eclipse.sirius.model/src-gen/org/eclipse/sirius/viewpoint/description/DocumentedElement.java

https://github.com/eclipse-sirius/sirius-desktop/blob/master/plugins/org.eclipse.sirius.model/src-gen/org/eclipse/sirius/viewpoint/description/EndUserDocumentedElement.java

And they are clearly identified.

I rebased this PR on #6249, which adds RepresentationDescription#endUserDocumentation.
This piece of code now uses this new field instead of the description.

Bug: #6248 Signed-off-by: Gwendal Daniel <gwendal.daniel@obeosoft.com>

Bug: #6243 Signed-off-by: Gwendal Daniel <gwendal.daniel@obeosoft.com>

gdaniel · 2026-03-04T15:40:47Z

...sirius/web/application/studio/services/representations/DomainDiagramDescriptionProvider.java

                .name("Domain")
                .domainType("domain::Domain")
                .titleExpression("aql:'Domain'")
+                .endUserDocumentation("A diagram showing the entities of a domain and their relations.")


We don't really need this, I added it to visually test the feature, but the integration test relies on a test-specific TestRepresentationDescriptionsProvider.

gdaniel force-pushed the gda/enh/descriptionInNewRepresentationModal branch from c0365f8 to 25e0949 Compare March 3, 2026 17:15

gdaniel added pr: to review soon priority: high labels Mar 3, 2026

gdaniel added this to the 2026.3.0 milestone Mar 3, 2026

gdaniel linked an issue Mar 3, 2026 that may be closed by this pull request

Add a description in the new representation modal #6243

Open

1 task

gdaniel force-pushed the gda/enh/descriptionInNewRepresentationModal branch from 25e0949 to 5829ce2 Compare March 3, 2026 17:23

gdaniel commented Mar 3, 2026

View reviewed changes

sbegaudeau requested changes Mar 4, 2026

View reviewed changes

gdaniel force-pushed the gda/enh/descriptionInNewRepresentationModal branch from 5829ce2 to 99187f7 Compare March 4, 2026 09:37

[6248] Add an endUserDocumentation field in RepresentationDescription

3172e48

Bug: #6248 Signed-off-by: Gwendal Daniel <gwendal.daniel@obeosoft.com>

gdaniel mentioned this pull request Mar 4, 2026

[6248] Add an endUserDocumentation field in RepresentationDescription #6249

Open

39 tasks

[6243] Add documentation in the new representation modal

414f803

Bug: #6243 Signed-off-by: Gwendal Daniel <gwendal.daniel@obeosoft.com>

gdaniel force-pushed the gda/enh/descriptionInNewRepresentationModal branch from 99187f7 to 414f803 Compare March 4, 2026 15:36

gdaniel changed the title ~~[6243] Add a description in the new representation modal~~ [6243] Add documentation in the new representation modal Mar 4, 2026

gdaniel commented Mar 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[6243] Add documentation in the new representation modal#6245

[6243] Add documentation in the new representation modal#6245
gdaniel wants to merge 2 commits intomasterfrom
gda/enh/descriptionInNewRepresentationModal

gdaniel commented Mar 3, 2026 •

edited

Loading

Uh oh!

gdaniel Mar 3, 2026

Uh oh!

sbegaudeau Mar 4, 2026

Uh oh!

gdaniel Mar 4, 2026

Uh oh!

gdaniel Mar 4, 2026

Uh oh!

gdaniel Mar 3, 2026

Uh oh!

sbegaudeau Mar 4, 2026

Uh oh!

gdaniel Mar 4, 2026

Uh oh!

gdaniel Mar 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

gdaniel commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request template

General purpose

Project management

Architectural decision records (ADR)

Dependencies

Frontend

General purpose

Typing

Backend

General purpose

Architecture

Review

How to test this PR?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gdaniel commented Mar 3, 2026 •

edited

Loading