expanding the contract to improve the usability of LabelAssignmentAction

core/src/main/java/hudson/model/Queue.java

@@ -1365,14 +1365,18 @@ public class Queue extends ResourceController implements Saveable {
      * to the queue, and the task will never get executed. 
      *
      * <p>
-     * This extension point is still a subject to change, as we are seeking more
-     * comprehensive Queue pluggability. See HUDSON-2072.
+     * The other use case is to add additional {@link Action}s to the task
+     * (for example {@link LabelAssignmentAction}) to tasks that are submitted to the queue.
      *
      * @since 1.316
      */
     public static abstract class QueueDecisionHandler implements ExtensionPoint {
     	/**
     	 * Returns whether the new item should be scheduled.
+         *
+         * @param actions
+         *      List of actions that are to be made available as {@link AbstractBuild#getActions()}
+         *      upon the start of the build. This list is live, and can be mutated.
     	 */
     	public abstract boolean shouldSchedule(Task p, List<Action> actions);
     	    	

core/src/main/java/hudson/model/labels/LabelAssignmentAction.java

@@ -2,13 +2,26 @@ package hudson.model.labels;
 
 import hudson.model.Action;
 import hudson.model.Label;
+import hudson.model.LoadBalancer;
 import hudson.model.Queue;
+import hudson.model.Queue.QueueDecisionHandler;
+import hudson.model.Queue.Task;
 import hudson.model.queue.SubTask;
 
 /**
  * {@link Action} that can be submitted to {@link Queue} that controls where
  * the task runs.
  *
+ * <h2>Where to insert {@link LabelAssignmentAction}s</h2>
+ * <p>
+ * If you control when the task gets submitted to the queue, you can associate this action
+ * to the task by passing it as a parameter to method like {@link Queue#schedule(Task, int, Action...)}.
+ *
+ * <p>
+ * If you want to globally affect the scheduling decision, you can do so by {@link QueueDecisionHandler}
+ * and alter the list of actions that you get. Alternatively, you can implement your own {@link LoadBalancer}
+ * and bypass the whole label/assignment mechanism to control the decision into your own hands.
+ *
  * @author Kohsuke Kawaguchi
  * @since 1.416
  */