Perhaps it is not needed to be added to @ActionReference, as (for example), the position of a new main menu called "Data" (say) shouldn't be influenced by individuals adding actions to that menu. What I mean is that it should not the responsibility of people adding actions to the Data menu to decide where the Data menu itself should be.

A possible layer-generating annotation could be

@FolderPosition(path="Menu/Data", position=1000) 

that generates

<filesystem>
    <folder name="Menu">
        <folder name="Data">
            <attr name="position" intvalue="1000"/>
        </folder>
    </folder>
</filesystem>

It would be better to not reveal that there is a layer behind all the annotations if possible. For example we could have:

@MenuRegistration(name="Data", displayName="My Data", position=1000)
@ActionReferences(....)

this would immediately mean that all the action references should go into Menu/Data folder.

Anyway, I don't have any plans to work on it, so find somebody to create a patch and go through API review.

I don't think @FolderPosition's path parameter exposes the presence of the layer more than (say) @ServiceProvider's path parameter - is it the annotation name that can be chosen better?

Also, my variation of the proposal is meant to be more general than just for menus or toolbars - it is intended as a way to reposition underlying folder positions in the layer (*), so it could (and perhaps should?) stand independently of the action annotations. I'm sure there are other use cases that could benefit from being able to reorder purely using annotations.

This is therefore intended as a standalone annotation, perhaps on package-info.java similar to OptionsPanelController.ContainerRegistration .

(*) JT: As you say, we would like to reorder folders in the layer, without choosing a name that would be too tightly coupled to the layer.

Created attachment 112355 [details]
Proposal

Adds 2 files to openide.awt - the @MenuRegistration annotation, as well as its annotation processor, MenuProcessor.java .

(In reply to comment #4)
> Created an attachment (id=112355) [details]
> Proposal
> 
> Adds 2 files to openide.awt - the @MenuRegistration annotation, as well as its
> annotation processor, MenuProcessor.java .

Here is a simplified version, for menus only. It does not have any effect on @ActionRegistration registrations, as this is intended as (for the most part) just a menu reordering. 

In this proposal, we would have

@MenuRegistration(location={"Data","SubMenu"}, displayName="My Data", position=1000)

generating

<filesystem>
   <folder name="Menu">
       <folder name="Data">
          <folder name="SubMenu">
             <attr name="displayName" stringvalue="My Data"/>
             <attr name="position" intvalue="1000"/>
          </folder>
       </folder>
   </folder>
</filesystem>

While the annotation is supported at package, type, method and field level, it is for the most part envisaged as to be used at the package level as typically @ActionReferences usage will refer to action registration in various different menus/toolbars/... .

An intermediate workaround is documented at https://blogs.oracle.com/geertjan/entry/ordering_of_netbeans_platform_menu