gpclient: Javadoc update

Author: gcarcassi

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

@@ -6,7 +6,8 @@
 
 /**
  * A PV that can be both read and written. In general, the read payload will be
- * different from the write payload.
+ * different from the write payload. See {@link PVReader} and {@link PVWriter} for
+ * more information.
  *
  * @param <R> type of the read payload
  * @param <W> type of the write payload

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

@@ -15,7 +15,7 @@
  * can be accessed from any thread,
  * but there is no guarantee on the atomicity. The only way to work on a consistent
  * snapshot is to use a listener and to process the event on the thread
- * of the listener. If the event is forwarded on another thread, one loses
+ * of the listener. If the event is forwarded to another thread, one loses
  * the atomicity and also the other safeguards (like rate throttling).
  * The callback does not lock the object, so other threads can still access
  * the object while listeners are executing.
@@ -30,7 +30,7 @@
  * state before the event processing started: since each element in the event
  * processing may be stateful, this becomes a non-trivial task. It would also not
  * cover a much simpler hole: the processing may be finished and the pause/stop
- * arrive during the use event callback. At that point, the framework has no control, so
+ * arrive during the user event callback. At that point, the framework has no control, so
  * you would still have a small chance of part of the callback executed after
  * pausing/closing. The solution there would be to lock the pause/close until
  * after all callbacks are done. This, which was the original implementation, has

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

@@ -5,7 +5,7 @@
 package org.epics.gpclient;
 
 /**
- * A write of a channel expression created through the {@link GPClient}. The write payload is specified by the generic type,
+ * A writer of a channel expression created through the {@link GPClient}. The write payload is specified by the generic type,
  * and is changed by {@link #write(java.lang.Object)}. Changes in
  * values are notified through the {@link PVWriterListener}. 
  * <p>

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

@@ -11,7 +11,7 @@
 
 /**
  * An expression used to set the final parameters on how the pv expression
- * should be read.
+ * should be written.
  * 
  * @param <T> the type of the expression
  * @author carcassi

gpclient/gpclient-core/src/main/java/org/epics/gpclient/datasource/CompositeDataSourceConfiguration.java

@@ -28,9 +28,18 @@ public final class CompositeDataSourceConfiguration {
     private String delimiter = "://";
     private String defaultDataSource;
 
+    /**
+     * Creates a new configuration.
+     */
     public CompositeDataSourceConfiguration() {
     }
 
+    /**
+     * Loads the configuration from the given input stream which must correspond
+     * to an XML file.
+     * 
+     * @param input the xml configuration
+     */
     public CompositeDataSourceConfiguration(InputStream input) {
         try {
             DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();

gpclient/gpclient-core/src/main/java/org/epics/gpclient/datasource/DataSource.java

@@ -101,8 +101,8 @@ protected String channelHandlerRegisterName(String channelName, ChannelHandler h
 
     // Keeps track of the recipes that were opened with
     // this data source.
-    private final Set<ReadSubscription> readSubscriptions = Collections.synchronizedSet(new HashSet<ReadSubscription>());
-    private final Set<WriteSubscription> writeSubscriptions = Collections.synchronizedSet(new HashSet<WriteSubscription>());
+    private final Set<ReadSubscription> readSubscriptions = Collections.synchronizedSet(new HashSet<>());
+    private final Set<WriteSubscription> writeSubscriptions = Collections.synchronizedSet(new HashSet<>());
 
     private final ProcessingQueue<ReadSubscription> startReadQueue = new ProcessingQueue<>(exec, new Consumer<List<ReadSubscription>>() {
         @Override
@@ -190,6 +190,11 @@ public void accept(List<WriteSubscription> list) {
         }
     });
 
+    /**
+     * Starts the given write subscription.
+     * 
+     * @param writeSubscription the subscription information
+     */
     public void startWrite(final WriteSubscription writeSubscription) {
         startWriteQueue.submit(writeSubscription);
     }
@@ -220,6 +225,11 @@ public void accept(List<WriteSubscription> list) {
         }
     });
 
+    /**
+     * Stops the given write subscription.
+     * 
+     * @param writeRecipe the subscription information
+     */
     public void stopWrite(final WriteSubscription writeRecipe) {
         stopWriteQueue.submit(writeRecipe);
     }

gpclient/gpclient-core/src/main/java/org/epics/gpclient/datasource/DataSourceProvider.java

@@ -10,7 +10,7 @@
 import java.util.logging.Logger;
 
 /**
- * A class that provides support for a DataSource.
+ * A class that provides support for a {@link DataSource}.
  * <p>
  * This interface allows different modules to registers a DataSource through
  * the ServiceLoader. Implementations that are correctly registered will
@@ -42,7 +42,7 @@ public abstract class DataSourceProvider {
     public abstract DataSource createInstance();
 
     /**
-     * Looks up the registered factories and creates a CompositeDataSource
+     * Looks up the registered factories and creates a {@link CompositeDataSource}
      * using them.
      * 
      * @return a new DataSource

gpclient/gpclient-core/src/main/java/org/epics/gpclient/datasource/DataSourceTypeAdapter.java

@@ -7,7 +7,7 @@
 import org.epics.gpclient.ReadCollector;
 
 /**
- * Matches and fills a cache with the data from connection and message payloads.
+ * Matches and sends notifies {@link ReadCollector}s with the data from connection and message payloads.
  * This optional class helps the writer of a datasource to manage the
  * type matching and conversions.
  *
@@ -30,7 +30,7 @@ public interface DataSourceTypeAdapter<ConnectionPayload, MessagePayload> {
 
     /**
      * The parameters required to open a monitor for the channel. The
-     * type of the parameters will be datasource specific
+     * type of the parameters will be datasource specific.
      * <p>
      * For channels multiplexed on a single subscription, this method
      * is never used.

gpclient/gpclient-core/src/main/java/org/epics/gpclient/datasource/package-info.java

@@ -0,0 +1,10 @@
+/**
+ * Copyright information and license terms for this software can be
+ * found in the file LICENSE.TXT included with the distribution.
+ */
+
+/**
+ * Defines the API to connect data sources to the EPICS General Purpose client (gpclient).
+ * 
+ */
+package org.epics.gpclient.datasource;

gpclient/gpclient-core/src/main/java/org/epics/gpclient/package-info.java

@@ -3,7 +3,7 @@
  * found in the file LICENSE.TXT included with the distribution.
  */
 /**
- * Main package of the EPICS General Purpose client (gpclient).
+ * Defines the core EPICS Generic Purpose client (gpclient) API.
  * <p>
  * The generic purpose client is meant to be used to build applications that 
  * are not specific to a particular deployment environment or to a particular use