It's original intent was to define the menu to slot into. And there was some hokey stuff to do with the action (@MemberOrder) sequence from which we inferred the order of the menus themselves.
We need to rationalise this. I suggest:
- we use menubars.layout.xml to define the order of the top-level menus, with no annotation equivalent. This is analogous to how rows, cols, fieldSets and tabs are only ever specified in object layouts with no annotation equivalent (ie the "higher level structure").
- we use @DomainServiceLayout(name="..." to identify the name of the menu to slot into. Within this, sequence is used to order across all other menu services that might be contributing actions to that menu. these would go into an un-named section of the service.
- We add a new element @DomainServiceLayout(sectionName=...) If specified, then the items would go into that section, if it exists in the menubars.layout.xml, with the sequence then being the order of actions in that section. Again, this is the higher-level structure thing.
- We would provide NO annotation for defining the order of the sections, these would only be in the menubars.layout.xml.
- menubars.layout.xml defines the order of menus, and the order of the sections within the menus
- @DomainServiceLayout(name=...) - identifies the menu
- @DomainServiceLayout(secitonName=...) - identifies the section within that menu
- @ActionLayout(sequence=...) defines the order of the actions within the section of the menu. This is either the unnamed-section (if sectionName=... is not defined) or in the explicitly named section (otherwise).