Javadoc corrections and improvements

Author: dhickin

normativeTypesJava/src/org/epics/nt/HasAlarm.java

@@ -10,6 +10,7 @@
 
 /**
  * Interface for pvData type wrappers with, possibly optional, alarm field.
+ * <p>
  * The alarm field should be a PVStructure conformant to the alarm
  * type alarm_t described in the NormativeTypes specification, which may or
  * may not have field name "alarm".
@@ -18,18 +19,18 @@
 public interface HasAlarm
 {
      /**
-      * Attach a PVAlarm.
-      * Will return false if no alarm field.
+      * Attaches a PVAlarm to an alarm field.
+      * Will return false if there is no alarm field.
       *
       * @param pvAlarm the PVAlarm to be attached
-      * @return true if the operation was successfull, otherwise false.
+      * @return true if the operation was successfull, otherwise false
       */
     public boolean attachAlarm(PVAlarm pvAlarm);
 
     /**
-     * Get the alarm field.
+     * Returns the alarm field.
      *
-     * @return the alarm field PVStructure, which may be null
+     * @return the alarm field or null if there is no alarm field
      */
     public PVStructure getAlarm();
 }

normativeTypesJava/src/org/epics/nt/HasControl.java

@@ -10,26 +10,27 @@
 
 /**
  * Interface for pvData type wrappers with, possibly optional, control field.
+ * <p>
  * The control field should be a PVStructure conformant to the control
  * type control_t described in the NormativeTypes specification, which may or
  * may not have field name "control".
  * @author dgh
  */
 public interface HasControl
 {
-     /**
-      * Attach a PVControl.
-      * Will return false if no control field.
-      *
-      * @param pvControl the PVControl to be attached
-      * @return true if the operation was successfull, otherwise false
-      */
+    /**
+     * Attaches a PVControl to the control field.
+     * Will return false if there is no control field.
+     *
+     * @param pvControl the PVControl to be attached
+     * @return true if the operation was successfull, otherwise false
+     */
     public boolean attachControl(PVControl pvControl);
 
     /**
-     * Get the control field.
+     * Returns the control field.
      *
-     * @return the control field PVStructure, which may be null
+     * @return the control field or null if there is no control field
      */
     public PVStructure getControl();
 }

normativeTypesJava/src/org/epics/nt/HasDisplay.java

@@ -10,26 +10,27 @@
 
 /**
  * Interface for pvData type wrappers with, possibly optional, display field.
+ * <p>
  * The display field should be a PVStructure conformant to the display
  * type display_t described in the NormativeTypes specification, which may or
  * may not have field name "display".
  * @author dgh
  */
 public interface HasDisplay
 {
-     /**
-      * Attach a PVDisplay.
-      * Will return false if no display field.
-      *
-      * @param pvDisplay the PVDisplay that will be attached
-      * @return true if the operation was successfull, otherwise false
-      */
+    /**
+     * Attaches a PVDisplay to the display field.
+     * Will return false if there is no display field.
+     *
+     * @param pvDisplay the PVDisplay that will be attached
+     * @return true if the operation was successfull, otherwise false
+     */
     public boolean attachDisplay(PVDisplay pvDisplay);
 
     /**
-     * Get the display field.
+     * Returns the display field.
      *
-     * @return PVStructure which may be null
+     * @return the display field or null if there is no display field
      */
     public PVStructure getDisplay();
 }

normativeTypesJava/src/org/epics/nt/HasTimeStamp.java

@@ -10,26 +10,27 @@
 
 /**
  * Interface for pvData type wrappers with, possibly optional, time stamp field.
+ * <p>
  * The time stamp field should be a PVStructure conformant to the time stamp
  * type time_t described in the NormativeTypes specification, which may or
  * may not have field name "timeStamp"
  * @author dgh
  */
 public interface HasTimeStamp
 {
-     /**
-      * Attach a PVTimeStamp.
-      * Will return false if no time stamp field.
-      *
-      * @param pvTimeStamp the PVTimeStamp that will be attached
-      * @return true if the operation was successfull, otherwise false
-      */
+    /**
+     * Attaches a PVTimeStamp to the time stamp field.
+     * Will return false if there is no time stamp field.
+     *
+     * @param pvTimeStamp the PVTimeStamp that will be attached
+     * @return true if the operation was successfull, otherwise false
+     */
     public boolean attachTimeStamp(PVTimeStamp pvTimeStamp);
 
     /**
-     * Get the timeStamp.
+     * Returns the time stamp field.
      *
-     * @return the time stamp PVStructure, which may be null
+     * @return the time tamp field or null if there is no time stamp field
      */
     public PVStructure getTimeStamp();
 }

normativeTypesJava/src/org/epics/nt/NTAggregate.java

@@ -32,10 +32,11 @@ public class NTAggregate
     /**
      * Creates an NTAggregate wrapping the specified PVStructure if the latter is compatible.
      * <p>
-     * Checks the supplied structure is compatible with NTAggregate
-     * and if so returns a NTAggregate which wraps it.
+     * Checks the supplied PVStructure is compatible with NTAggregate
+     * and if so returns an NTAggregate which wraps it.
      * This method will return null if the structure is is not compatible
      * or is null.
+     *
      * @param pvStructure the PVStructure to be wrapped
      * @return the NTAggregate instance on success, null otherwise
      */
@@ -61,10 +62,10 @@ public static NTAggregate wrapUnsafe(PVStructure pvStructure)
     }
 
     /**
-     * Checks if the specified structure reports to be a compatible NTAggregate.
+     * Returns whether the specified Structure reports to be a compatible NTAggregate.
      * <p>
-     * Checks whether the specified structure reports compatibility with this
-     * version of NTAggregate through type ID, including checking version numbers.
+     * Checks if the specified Structure reports compatibility with this
+     * version of NTAggregate through its type ID, including checking version numbers.
      * The return value does not depend on whether the structure is actually
      * compatible in terms of its introspection type.
      *
@@ -77,10 +78,10 @@ public static boolean is_a(Structure structure)
     }
 
     /**
-     * Checks if the specified structure reports to be a compatible NTAggregate.
+     * Returns whether the specified PVStructure reports to be a compatible NTAggregate.
      * <p>
-     * Checks whether the specified structure reports compatibility with this
-     * version of NTAggregate through type ID, including checking version numbers.
+     * Checks if the specified PVStructure reports compatibility with this
+     * version of NTAggregate through its type ID, including checking version numbers.
      * The return value does not depend on whether the structure is actually
      * compatible in terms of its introspection type.
      *
@@ -93,10 +94,10 @@ public static boolean is_a(PVStructure pvStructure)
     }
 
     /**
-     * Checks if the specified structure is compatible with NTAggregate.
+     * Returns whether the specified Structure is compatible with NTAggregate.
      * <p>
-     * Checks whether the specified structure is compatible with this version
-     * of NTAggregate through introspection interface.
+     * Checks if the specified Structure is compatible with this version
+     * of NTAggregate through the introspection interface.
      *
      * @param structure the Structure to test
      * @return (false,true) if (is not, is) a compatible NTAggregate
@@ -181,10 +182,10 @@ public static boolean isCompatible(Structure structure)
     }
 
     /**
-     * Checks if the specified structure is compatible with NTAggregate.
+     * Returns whether the specified PVStructure is compatible with NTAggregate.
      * <p>
-     * Checks whether the specified structure is compatible with this version
-     * of NTAggregate through introspection interface.
+     * Checks if the specified PVStructure is compatible with this version
+     * of NTAggregate through the introspection interface.
      *
      * @param pvStructure the PVStructure to test
      * @return (false,true) if (is not, is) a compatible NTAggregate
@@ -197,20 +198,21 @@ public static boolean isCompatible(PVStructure pvStructure)
     }
 
     /**
-     * Checks if the specified structure is a valid NTAggregate.
-     * <p>
-     * Checks whether the wrapped structure is valid with respect to this
+     * Returns whether the wrapped PVStructure is valid with respect to this
      * version of NTAggregate.
+     * <p>
+     * Unlike isCompatible(), isValid() may perform checks on the value
+     * data as well as the introspection data.
      *
-     * @return (false,true) if (is not, is) a valid NTAggregate
+     * @return (false,true) if wrapped PVStructure (is not, is) a valid NTAggregate
      */
     public boolean isValid()
     {
         return true;
     }
 
     /**
-     * Create an NTAggregate builder instance.
+     * Creates an NTAggregate builder instance.
      *
      * @return builder instance.
      */
@@ -220,109 +222,109 @@ public static NTAggregateBuilder createBuilder()
     }
 
     /**
-     * Get the pvStructure.
+     * Returns the PVStructure wrapped by this instance.
      *
-     * @return PVStructure
+     * @return the PVStructure wrapped by this instance
      */
     public PVStructure getPVStructure()
     {
         return pvNTAggregate;
     }
 
     /**
-     * Get the value field.
+     * Returns the value field.
      *
-     * @return the PVDouble for the aggregate
+     * @return the value field
      */
     public PVDouble getValue()
     {
         return pvValue;
     }
 
     /**
-     * Get the N field.
+     * Returns the N field.
      *
-     * @return the PVLong for the aggregate
+     * @return the N field
      */
     public PVLong getN()
     {
         return pvNTAggregate.getSubField(PVLong.class, "N");
     }
 
     /**
-     * Get the dispersion field.
+     * Returns the dispersion field.
      *
-     * @return the PVDouble for the aggregate
+     * @return the dispersion or null if no such field
      */
     public PVDouble getDispersion()
     {
         return pvNTAggregate.getSubField(PVDouble.class, "dispersion");
     }
 
     /**
-     * Get the first field.
-     *
-     * @return the last value for the aggregate
+     * Returns the first field.
+
+     * @return the first field or null if no such field
      */
     public PVDouble getFirst()
     {
         return pvNTAggregate.getSubField(PVDouble.class, "first");
     }
 
     /**
-     * Get the firstTimeStamp field.
+     * Returns the firstTimeStamp field.
      *
-     * @return the timeStamp for the first value of the aggregate
+     * @return the firstTimeStamp field or null if no such field
      */
     public PVStructure getFirstTimeStamp()
     {
         return pvNTAggregate.getSubField(PVStructure.class, "firstTimeStamp");
     }
 
     /**
-     * Get the last field.
+     * Returns the last field.
      *
-     * @return the last value for the aggregate
+     * @return the last field or null if no such field
      */
     public PVDouble getLast()
     {
         return pvNTAggregate.getSubField(PVDouble.class, "last");
     }
 
     /**
-     * Get the lastTimeStamp field.
+     * Returns the lastTimeStamp field.
      *
-     * @return the timeStamp for the last value of the aggregate
+     * @return the lastTimeStamp field or null if no such field
      */
     public PVStructure getLastTimeStamp()
     {
         return pvNTAggregate.getSubField(PVStructure.class, "lastTimeStamp");
     }
 
     /**
-     * Get the max field.
+     * Returns the max field.
      *
-     * @return the max for the aggregate
+     * @return the max field or null if no such field
      */
     public PVDouble getMax()
     {
         return pvNTAggregate.getSubField(PVDouble.class, "max");
     }
 
     /**
-     * Get the min field.
+     * Returns the min field.
      *
-     * @return the max for the aggregate
+     * @return the min field or null if no such field
      */
     public PVDouble getMin()
     {
         return pvNTAggregate.getSubField(PVDouble.class, "min");
     }
 
     /**
-     * Get the descriptor field.
+     * Returns the descriptor field.
      *
-     * @return the PVString or null if no descriptor field
+     * @return the descriptor field or null if no such field
      */
     public PVString getDescriptor()
     {