Clean up javadoc and make assertions clearer in SignalSlot

sherpa-java/src/main/java/sherpa/client/SignalSlot.java

@@ -26,16 +26,19 @@ class SignalSlot <T> {
    * the old data has already been retrieved as it will be 
    * clobbered.
    *  
-   * @param data Put the data into the slot
+   * @param data Put the data into the slot. data should never be null.
    */ 
   public void add(T data) {
+    assert data != null;
     writeSlot(data, null);
   }
 
   /** 
    * Interrupt a waiting reader and put the slot into an error state. 
+   * @param t The error, should never be null
    */
   public void addError(Throwable t) {
+    assert t != null;
     writeSlot(null, t);
   }
 
@@ -53,7 +56,7 @@ private void writeSlot(T data, Throwable error) {
 
   /**
    * Get and clear the slot - MUST be called while holding the lock!! 
-   * @return The data
+   * @return The data or null if no data or error exists
    * @throws Throwable If producer encountered an error
    */
   private T getAndClearUnderLock() throws Throwable {
@@ -82,21 +85,23 @@ public T poll() throws Throwable {
   }
 
   /** 
-   * Blocking read and remove. If return is null, the thread
-   * was interrupted by the producer.
-   * @return The data or null if interrupted 
+   * Blocking read and remove. If the thread was interrupted by 
+   * the producer due to an error, the producer's error will be thrown.
+   * @return The data, should never be null
    * @throws Throwable If producer encountered an error
    */
   public T take() throws Throwable {
     dataLock.lock();      
     try {
-      while(data == null && error == null) {   // loop in case of spurious wake-ups
+      while(data == null && error == null) {
         try {
           availableCondition.await();
         } catch(InterruptedException e) {
-          // ignore and re-loop
+          // ignore and re-loop in case of spurious wake-ups
         }
       }
+
+      // should only get to here if data or error is non-null
       return getAndClearUnderLock();
     } finally {
       dataLock.unlock();