Linking to model elements in doc element markdown strings

Syside Feature Requests
1

Hi,

The Modeler feature that shows a tooltip with formatted markdown of a model elements’ `doc` object is very nice. Is it possible to reference/ add hyperlinks in the doc text to actual model elements? Something like

part def MyPart {
  doc /* here is my part */
}

part useIt : MyPart {
  doc /* this usage is defined by @$::MyModel::MyPart.
}

Then the user can hover over a definition, read the text, if there is a hyperlink, they can click it in the tooltip and be transported to that definition (in vs code), or in built documentation (eg a static site), transported to that page of the model reference docs.

It would probably also be useful to know if Modeler can interpret / navigate markdown anchor links?

A further application - users create a glossary of system terms in the model, and in doc strings, can reference them:

package ModelGlossary {
    item def State {
        doc
        /* A specific condition of a system at a point in time. */
    }
}

package MyModel {
  part def MyState {
    doc /* A [state]($::ModelGlossary::State) of the system. */
  }
}

thanks!

2

Hi,

Resolving links to symbols is something we could definitely add in the future, we just have more important issues/features to resolve in the meantime.

Currently, Syside simply forwards the source docstring(s) to the client for rendering so all hyperlinks will have to be written manually.

3

Hi Daumantas,

ok no problem. Related follow-on:

It is useful to write documentation about the model within the model, because of this syside modeler feature (vs code tooltips- i dont need to leave the tool to learn what a model element does). However once the docs start getting extensive, it bloats the model file and may overwhelm new team members trying to absorb the structure of the model.

An alternative could be to use the `doc about ` feature of sysml. Then i could write the docs in a separate file. As far as I can tell, syside modeler does not pickup docs about an element from different files in the project and displays them in the tooltip?

4

Partial answer to my last post: I believe the sysmlv2 spec does not allow the doc element to use the aboutkeyword, since a doc is always about its parent/ owning element. So the above would have to be done with comment about.

I believe syside modeler still does not pick up those comments if made in a different location.

5

I would not recommend having documentation separate from anything it describes because tooling will not always be available, e.g. when browsing sources on GitHub or GitLab. Additionally, documentation should be an explanation of why certain choices were made, and how the documented symbol should be used, not necessarily describing what it is doing as it should be clear from the code itself. Perhaps if you feel like it is getting bloated, leave links to external resources, e.g. data sheets, instead. Most of the editors support markdown syntax for links [<text>](<url>), relative urls may or may not be supported, Syside just forwards the contents to the editor for rendering.

Yeah, SysML grammar does not allow about keyword on `docs.

comments are not used for hover contents, only docs.

6

Thanks Daumantas, you’ve answered everything.