svn commit: r1796883 - /pivot/trunk/core/src/org/apache/pivot/util/Vote.java

[rw...@apache.org]

Author: rwhitcomb
Date: Tue May 30 15:32:52 2017
New Revision: 1796883

URL: http://svn.apache.org/viewvc?rev=1796883&view=rev
Log:
Add Javadoc to the Vote.tally() method to explain the algorithm.
Use Utils.checkNull() in there also.

Modified:
    pivot/trunk/core/src/org/apache/pivot/util/Vote.java

Modified: pivot/trunk/core/src/org/apache/pivot/util/Vote.java
URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/util/Vote.java?rev=1796883&r1=1796882&r2=1796883&view=diff
==============================================================================
--- pivot/trunk/core/src/org/apache/pivot/util/Vote.java (original)
+++ pivot/trunk/core/src/org/apache/pivot/util/Vote.java Tue May 30 15:32:52 2017
@@ -37,31 +37,42 @@ public enum Vote {
      */
     DEFER;
 
+    /**
+     * Tally a new vote against the previous tally result.
+     * For a vote tally to work correctly the initial value must be {@link #APPROVE}.
+     * <p>The tallying algorithm is as follows:
+     * <ul>
+     * <li>New vote is {@link #APPROVE} -&gt; result is previous result.
+     * <li>New vote is {@link #DENY} -&gt; result is new vote (that is, <tt>DENY</tt>).
+     * <li>New vote is {@link #DEFER} -&gt; result is <tt>DENY</tt> if previous was
+     * <tt>DENY</tt>, otherwise <tt>DEFER</tt>.
+     * </ul>
+     *
+     * @param vote The new vote to tally.
+     * @return The result of tallying this new vote against this
+     * previously accumulated result.
+     * @throws IllegalArgumentException if the new vote is {@code null}.
+     */
     public Vote tally(Vote vote) {
-        if (vote == null) {
-            throw new IllegalArgumentException();
-        }
+        Utils.checkNull(vote, "vote");
 
         Vote tally;
 
         switch (vote) {
-            case APPROVE: {
+            case APPROVE:
                 tally = this;
                 break;
-            }
 
-            case DENY: {
+            case DENY:
                 tally = vote;
                 break;
-            }
 
-            case DEFER: {
+            case DEFER:
                 tally = (this == DENY) ? this : vote;
                 break;
-            }
 
             default: {
-                throw new IllegalArgumentException();
+                throw new IllegalArgumentException("Unknown Vote value to tally.");
             }
         }