Document exceptions and satisfy codacy's demands.

gcloud-java-core/src/main/java/com/google/gcloud/IamPolicy.java

@@ -58,6 +58,9 @@ public abstract static class Builder<R, B extends Builder<R, B>> {
     private String etag;
     private Integer version;
 
+    /**
+     * Constructor for IAM Policy builder.
+     */
     protected Builder() {}
 
     /**
@@ -73,6 +76,8 @@ public final B bindings(Map<R, Set<Identity>> bindings) {
 
     /**
      * Adds a binding to the policy.
+     *
+     * @throws IllegalArgumentException if the policy already contains a binding with the same role
      */
     public final B addBinding(R role, Set<Identity> identities) {
       checkArgument(!bindings.containsKey(role),
@@ -83,6 +88,8 @@ public final B addBinding(R role, Set<Identity> identities) {
 
     /**
      * Adds a binding to the policy.
+     *
+     * @throws IllegalArgumentException if the policy already contains a binding with the same role
      */
     public final B addBinding(R role, Identity first, Identity... others) {
       checkArgument(!bindings.containsKey(role),
@@ -104,8 +111,12 @@ public final B removeBinding(R role) {
 
     /**
      * Adds one or more identities to an existing binding.
+     *
+     * @throws IllegalArgumentException if the policy doesn't contain a binding with the specified
+     *     role
      */
     public final B addIdentity(R role, Identity first, Identity... others) {
+      checkArgument(bindings.containsKey(role), "The policy doesn't contain the specified role.");
       Set<Identity> identities = bindings.get(role);
       identities.add(first);
       identities.addAll(Arrays.asList(others));
@@ -114,8 +125,12 @@ public final B addIdentity(R role, Identity first, Identity... others) {
 
     /**
      * Removes one or more identities from an existing binding.
+     *
+     * @throws IllegalArgumentException if the policy doesn't contain a binding with the specified
+     *     role
      */
     public final B removeIdentity(R role, Identity first, Identity... others) {
+      checkArgument(bindings.containsKey(role), "The policy doesn't contain the specified role.");
       bindings.get(role).remove(first);
       bindings.get(role).removeAll(Arrays.asList(others));
       return self();

gcloud-java-core/src/test/java/com/google/gcloud/IdentityTest.java

@@ -18,7 +18,6 @@
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNull;
-import static org.junit.Assert.fail;
 
 import org.junit.Test;
 
@@ -48,48 +47,44 @@ public void testAllAuthenticatedUsers() {
   public void testUser() {
     assertEquals(Identity.Type.USER, USER.type());
     assertEquals("abc@gmail.com", USER.id());
-    try {
-      Identity.user(null);
-      fail("Should have thrown exception due to null email address.");
-    } catch (NullPointerException e) {
-      // expected
-    }
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testUserNullEmail() {
+    Identity.user(null);
   }
 
   @Test
   public void testServiceAccount() {
     assertEquals(Identity.Type.SERVICE_ACCOUNT, SERVICE_ACCOUNT.type());
     assertEquals("service-account@gmail.com", SERVICE_ACCOUNT.id());
-    try {
-      Identity.serviceAccount(null);
-      fail("Should have thrown exception due to null email address.");
-    } catch (NullPointerException e) {
-      // expected
-    }
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testServiceAccountNullEmail() {
+    Identity.serviceAccount(null);
   }
 
   @Test
   public void testGroup() {
     assertEquals(Identity.Type.GROUP, GROUP.type());
     assertEquals("group@gmail.com", GROUP.id());
-    try {
-      Identity.group(null);
-      fail("Should have thrown exception due to null email address.");
-    } catch (NullPointerException e) {
-      // expected
-    }
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testGroupNullEmail() {
+    Identity.group(null);
   }
 
   @Test
   public void testDomain() {
     assertEquals(Identity.Type.DOMAIN, DOMAIN.type());
     assertEquals("google.com", DOMAIN.id());
-    try {
-      Identity.domain(null);
-      fail("Should have thrown exception due to null domain.");
-    } catch (NullPointerException e) {
-      // expected
-    }
+  }
+
+  @Test(expected = NullPointerException.class)
+  public void testDomainNullId() {
+    Identity.domain(null);
   }
 
   @Test