search

itemisCREATE / statecharts

YAKINDU Statechart Tools (http://www.statecharts.org)
Eclipse Public License 1.0
176 stars 86 forks source link

Documentation flaws #2781

Open bselic opened 5 years ago

bselic commented 5 years ago

In the Yakindu Statechart reference documentation there are a number of misrepresentations of the UML standard that I think should be fixed, despite the fact that you are not claiming to be UML compliant (it is not appropriate to spread misinformation). For example, in section 7.3.3.1 it says the following:

_A standard UML composite state is always entered via its initial state. The latter denotes the inner state that is to be activated, unless a history state tells otherwise. Since there can be only a single initial state per region, a standard UML composite state always starts at the same inner state (history states aside).

Unlike UML composite states, however, composite states in YAKINDU statecharts can additionally denote specific named entry points. A transition leading to a composite state can specify the entry point to be used instead of the initial state.

Analogously, a composite state can have named exit points. Outgoing transitions of that composite state may specify which exit point to react to, and thus lead to different target states, depending on which of the source composite state’s exit points has been taken. A blank transition with no trigger or guard reacts to all exit points, and is needed when a composite state contains a default exit point._

For the record, UML does support both entry and exit points (as of UML 2.0) that are semantically equivalent to what Yakindu supports, although the concrete notation is diferent. There are other such examples that I ran across reading the documentation. I happen to be one of the authors of the UML standard, and I hope that you will understand that I am bothered when my work is misrepresented - as I am sure you would be as well.

So, my request is that you review the latest UML standard (including the Precise Semantics of UML State Machines OMG standard) and fix any mistaken claims about UML.

Actually, since you do support various statechart semantics, why not actually provide a version that is UML standard compatible?

Cheers... Bran Selic

terfloth commented 5 years ago

Dear Bran,

thank you for opening the issue. Please be sure that we neither want to bother you nor want to misrepresent the UML.

The text that you quoted is obviously not complete as it does not mention UML entryPoint and exitPoint pseudostates. So i agree with you that this is a bug in the documentation. YAKINDU does not define different model elements for initial, shallowHistory, deepHistory, and entryPoint pseudostates. There is just an EntryNode which defines how a region is entered and an ExitNode that forces an exit. Entry and exit nodes are optionally named and each entry node defines a history property (no, shallow, deep). The YAKINDU ExitNode is semantically identical to the UML exitPoint. I think the relation to the UML can be better described in such a way...

Updating the documentation is a major topic anyway and we will also have a look at those parts that relate to the UML.

I've not taken a closer look at the PSSM specification yet. But as the PSSM standard is published now it could become relevant for our users. From a technical point of view i see no reasons why a native PSSM support could not be possible. We already have provide a SCXML compliant flavor and also support for ALf as action language would be possible.