Document nullability of newInstanceFromRadioList() methods and… (#4543)

core/src/main/java/hudson/DescriptorExtensionList.java

@@ -46,6 +46,7 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 import java.util.concurrent.CopyOnWriteArrayList;
 import javax.annotation.CheckForNull;
+import javax.annotation.Nonnull;
 
 import net.sf.json.JSONException;
 import org.kohsuke.stapler.Stapler;
@@ -133,10 +134,14 @@ public class DescriptorExtensionList<T extends Describable<T>, D extends Descrip
     }
 
     /**
-     * Creates a new instance of a {@link Describable}
-     * from the structured form submission data posted
-     * by a radio button group.
+     * Creates a new instance of a {@link Describable} from the structured form submission data posted by a radio button group.
+     * @param config Submitted configuration for Radio List
+     * @return New instance.
+     *         {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter}
+     * @throws FormException Data submission error
+     * @since 1.312
      */
+    @CheckForNull
     public T newInstanceFromRadioList(JSONObject config) throws FormException {
         if(config.isNullObject())
             return null;    // none was selected
@@ -144,7 +149,16 @@ public class DescriptorExtensionList<T extends Describable<T>, D extends Descrip
         return get(idx).newInstance(Stapler.getCurrentRequest(),config);
     }
 
-    public T newInstanceFromRadioList(JSONObject parent, String name) throws FormException {
+    /**
+     * Creates a new instance of a {@link Describable} from the structured form submission data posted by a radio list.
+     * @since 1.312
+     * @param name Name of the form field
+     * @return Created instance.
+     *         {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter}
+     * @throws FormException Data submission error
+     */
+    @CheckForNull
+    public T newInstanceFromRadioList(@Nonnull JSONObject parent, @Nonnull String name) throws FormException {
         try {
             return newInstanceFromRadioList(parent.getJSONObject(name));
         } catch (JSONException ex) {

core/src/main/java/hudson/util/DescriptorList.java

@@ -151,7 +151,8 @@ public final class DescriptorList<T extends Describable<T>> extends AbstractList
      * from the structured form submission data posted
      * by a radio button group. 
      * @param config Submitted configuration for Radio List
-     * @return new instance or {@code null} if none was selected in the radio list
+     * @return New instance.
+     *         {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter}
      * @throws FormException Data submission error
      */
     @CheckForNull
@@ -168,7 +169,8 @@ public final class DescriptorList<T extends Describable<T>> extends AbstractList
      * by a radio button group. 
      * @param parent JSON, which contains the configuration entry for the radio list
      * @param name Name of the configuration entry for the radio list
-     * @return new instance or {@code null} if none was selected in the radio list
+     * @return New instance.
+     *         {@code null} if none was selected in the radio list or if the value is filtered by a {@link hudson.model.DescriptorVisibilityFilter}
      * @throws FormException Data submission error
      */
     @CheckForNull

core/src/main/java/jenkins/model/Jenkins.java

@@ -2604,7 +2604,12 @@ public class Jenkins extends AbstractCIBase implements DirectlyModifiableTopLeve
         return securityRealm;
     }
 
-    public void setSecurityRealm(SecurityRealm securityRealm) {
+    /**
+     * Sets a security realm.
+     * @param securityRealm Security realm to set.
+     *                      If {@code null}, {@link SecurityRealm#NO_AUTHENTICATION} will be set.
+     */
+    public void setSecurityRealm(@CheckForNull SecurityRealm securityRealm) {
         if(securityRealm==null)
             securityRealm= SecurityRealm.NO_AUTHENTICATION;
         this.useSecurity = true;
@@ -2634,7 +2639,12 @@ public class Jenkins extends AbstractCIBase implements DirectlyModifiableTopLeve
         saveQuietly();
     }
 
-    public void setAuthorizationStrategy(AuthorizationStrategy a) {
+    /**
+     * Sets a new authorization strategy.
+     * @param a Authorization strategy to set.
+     *          If {@code null}, {@link AuthorizationStrategy#UNSECURED} will be set
+     */
+    public void setAuthorizationStrategy(@CheckForNull AuthorizationStrategy a) {
         if (a == null)
             a = AuthorizationStrategy.UNSECURED;
         useSecurity = true;