gpclient: Javadoc update

Author: gcarcassi

gpclient/gpclient-core/src/main/java/org/epics/gpclient/PVEvent.java

@@ -21,7 +21,51 @@
  * @author carcassi
  */
 public final class PVEvent {
-    public enum Type {READ_CONNECTION, WRITE_CONNECTION, VALUE, EXCEPTION, WRITE_SUCCEEDED, WRITE_FAILED};
+    /**
+     * The type of the event.
+     */
+    public enum Type {
+        /**
+         * The read connection value has changed. For example, the network
+         * channel was connected/disconnected, the read access rights were
+         * changed, ...
+         */
+        READ_CONNECTION,
+        
+        /**
+         * The write connection value has changed. For example, the network
+         * channel was connected/disconnected, the write access rights were
+         * changed, ...
+         */
+        WRITE_CONNECTION,
+        
+        /**
+         * The value has changed. For example, a new value was posted for
+         * this channel, the metadata associated with it changed, ...
+         */
+        VALUE,
+        
+        /**
+         * An error was posted on this channel. For example, a timeout expired,
+         * the channel was not found, the value did not match the type requested, .,..
+         */
+        EXCEPTION,
+        
+        /**
+         * The write was successful. The exact meaning will depend on the
+         * channel. For example, one channel may return successful if the value
+         * was posted successfully, one may return successful only if the value
+         * was processed correctly, ...
+         */
+        WRITE_SUCCEEDED,
+        
+        /**
+         * The write was not successful. The exact meaning will depend on the
+         * channel. For example, one channel may deem the write failed even
+         * if the value was received correctly, but its processing caused
+         * an error.
+         */
+        WRITE_FAILED};
 
     private final List<Type> types;
     private final Exception exception;
@@ -36,23 +80,53 @@ private PVEvent(Exception ex, Exception writeError, List<Type> types) {
     private PVEvent(Type type) {
         this(null, null, Collections.singletonList(type));
     }
-    
+
+    /**
+     * Checks whether the type of this event contains the given type.
+     * 
+     * @param type an event type
+     * @return true if this event is of that type
+     */
     public boolean isType(Type type) {
         return types.contains(type);
     }
 
+    /**
+     * All the types of this event. An event may be aggregated and can, therefore,
+     * map to more than one type.
+     * 
+     * @return the type list
+     */
     public List<Type> getType() {
         return types;
     }
 
+    /**
+     * If the type is {@link Type#EXCEPTION}, it contains the exception. Null
+     * otherwise.
+     * 
+     * @return the error associated with the event
+     */
     public Exception getException() {
         return exception;
     }
 
+    /**
+     * If the type is {@link Type#WRITE_FAILED}, it contains the error. Null
+     * otherwise.
+     * 
+     * @return the error associated with the event
+     */
     public Exception getWriteError() {
         return writeError;
     }
-    
+
+    /**
+     * Returns a new event that aggregates this event with the given event.
+     * 
+     * @param event the event to aggregate to this
+     * @return the new aggregated event
+     */
     public PVEvent addEvent(PVEvent event) {
         List<Type> newTypes = new ArrayList<>(getType());
         for (Type type : event.getType()) {
@@ -126,31 +200,68 @@ public String toString() {
     private static final PVEvent READ_CONNECTION_VALUE_EVENT = new PVEvent(null, null, Arrays.asList(Type.READ_CONNECTION, Type.VALUE));
     private static final PVEvent WRITE_CONNECTION_EVENT = new PVEvent(Type.WRITE_CONNECTION);
     private static final PVEvent WRITE_SUCCEEDED_EVENT = new PVEvent(Type.WRITE_SUCCEEDED);
-    
+
+    /**
+     * A read connection event.
+     * 
+     * @return an event
+     */
     public static PVEvent readConnectionEvent() {
         return READ_CONNECTION_EVENT;
     }
 
+    /**
+     * A value event.
+     * 
+     * @return an event
+     */
     public static PVEvent valueEvent() {
         return VALUE_EVENT;
     }
-    
+
+    /**
+     * A read connection and value event.
+     * 
+     * @return an event
+     */
     public static PVEvent readConnectionValueEvent() {
         return READ_CONNECTION_VALUE_EVENT;
     }
-    
+
+    /**
+     * An exception event.
+     * 
+     * @param ex the exception to associate with the event
+     * @return an event
+     */
     public static PVEvent exceptionEvent(Exception ex) {
         return new PVEvent(ex, null, Collections.singletonList(Type.EXCEPTION));
     }
 
+    /**
+     * A write connection event.
+     * 
+     * @return an event
+     */
     public static PVEvent writeConnectionEvent() {
         return WRITE_CONNECTION_EVENT;
     }
 
+    /**
+     * A write succeeded event.
+     * 
+     * @return an event
+     */
     public static PVEvent writeSucceededEvent() {
         return WRITE_SUCCEEDED_EVENT;
     }
-    
+
+    /**
+     * A write failed event.
+     * 
+     * @param writeError the error associated with the write
+     * @return an event
+     */
     public static PVEvent writeFailedEvent(Exception writeError) {
         return new PVEvent(null, writeError, Collections.singletonList(Type.WRITE_FAILED));
     }