Code documentation/annotation around JENKINS-28446.

Just to prevent similar misuses in the future.
jenkinsci · May 18, 2015 · 298e371 · 298e371
1 parent 8373984
commit 298e371
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 7 deletions.
diff --git a/core/src/main/java/hudson/model/Queue.java b/core/src/main/java/hudson/model/Queue.java
@@ -124,6 +124,7 @@
 import com.thoughtworks.xstream.XStream;
 import com.thoughtworks.xstream.converters.basic.AbstractSingleValueConverter;
 import javax.annotation.CheckForNull;
+import javax.annotation.Nonnegative;
 import jenkins.model.queue.AsynchronousExecution;
 import org.kohsuke.stapler.QueryParameter;
 import org.kohsuke.stapler.interceptor.RequirePOST;
@@ -942,8 +943,10 @@ public boolean isPending(Task t) {
 
     /**
      * How many {@link BuildableItem}s are assigned for the given label?
+     * @param l Label to be checked. If null, any label will be accepted
+     * @return Number of {@link BuildableItem}s for the specified label. 
      */
-    public int countBuildableItemsFor(Label l) {
+    public @Nonnegative int countBuildableItemsFor(@CheckForNull Label l) {
         Snapshot snapshot = this.snapshot;
         int r = 0;
         for (BuildableItem bi : snapshot.buildables)
@@ -1808,13 +1811,16 @@ public Label getAssignedLabel() {
         }
 
         /**
-         * Test if the specified {@link SubTask} needs to be run on a node with a particular label, and
-         * return that {@link Label}. Otherwise null, indicating it can run on anywhere.
-         *
+         * Test if the specified {@link SubTask} needs to be run on a node with a particular label.
          * <p>
-         * This code takes {@link LabelAssignmentAction} into account, then falls back to {@link SubTask#getAssignedLabel()}
+         * This method takes {@link LabelAssignmentAction} into account, the first
+         * non-null assignment will be returned. 
+         * Otherwise falls back to {@link SubTask#getAssignedLabel()}
+         * @param st {@link SubTask} to be checked.
+         * @return Required {@link Label}. Otherwise null, indicating it can run on anywhere.
+
          */
-        public Label getAssignedLabelFor(SubTask st) {
+        public @CheckForNull Label getAssignedLabelFor(@Nonnull SubTask st) {
             for (LabelAssignmentAction laa : getActions(LabelAssignmentAction.class)) {
                 Label l = laa.getAssignedLabel(st);
                 if (l!=null)    return l;

diff --git a/core/src/main/java/hudson/model/labels/LabelAssignmentAction.java b/core/src/main/java/hudson/model/labels/LabelAssignmentAction.java
@@ -7,6 +7,7 @@
 import hudson.model.Queue.QueueDecisionHandler;
 import hudson.model.Queue.Task;
 import hudson.model.queue.SubTask;
+import javax.annotation.Nonnull;
 
 /**
  * {@link Action} that can be submitted to {@link Queue} that controls where
@@ -35,5 +36,5 @@ public interface LabelAssignmentAction extends Action {
      *      null to let other {@link LabelAssignmentAction}s take control, eventually to {@code SubTask#getAssignedLabel()}.
      *      If non-null value is returned, that label will be authoritative.
      */
-    Label getAssignedLabel(SubTask task);
+    Label getAssignedLabel(@Nonnull SubTask task);
 }