For my part I don't agree fully. I'd like to see them parsed in (2), too. This could be valueable information at runtime which could be retrieved via the API to use it in your own application. It would also allow you to use short names for transititions while having long descriptions available in case you need them.
I believe that transition descriptions would be useful too, but the description element as it appears in the current schema does not seem to fit that purpose. The transitionType definition appears below. Annotations have been removed for brevity.
<complexType name="transitionType"> <sequence> <element name="description" minOccurs="0" maxOccurs="unbounded" type="string" /> <group ref="tns:eventListenerGroup" minOccurs="0" maxOccurs="unbounded" /> </sequence> <attribute name="name" type="string"/> <attribute name="to" type="string"/> <attribute name="g" type="string"/> </complexType>
- in the description element, maxOccurs is set to unbounded. The contents of which description element should be set as the transition description? The first? The concatenation of all of them? Why are multiple descriptions allowed in the first place?
- multiple event listeners may occur after the description(s). In my original comment I thought the intent was to allow each event listener to be preceded by a description, but the schema as it currently stands does not allow that.
In sum it all comes down to intent. Is the description intended to apply to the transition (in which case maxOccurs should be set to one) or to optionally precede each event listener (in which case the unbounded maxOccurs should be moved from the description and the eventListenerGroup to the sequence)?
Personally I'd see the description as a child element of the parent and not related to it's brother/sister at all. So one should be enough. Multiple eventlisteners? On the transition? hmmm... no idea, probably one should be sufficient.
Regarding the description-element I agree with Ronald but regarding the event-listeners I think we should offer the possibility to have multiple event-listeners on a transition. Imagine you've got a bunch of listeners suiting different use cases in a modular way and you want to be able to combine them for specific situations. Furthermore I think it would be good if the description could be used in the process diagramm.