address some javadocs omissions

java/src/jmri/jmrix/loconet/AbstractAlmImplementation.java

@@ -205,24 +205,28 @@ void writeMsg(LocoNetMessage msg) {
 
     /**
      * Notify possible subclass that a block has changed.
+     * @param block - something about a block
      */
     public void noteChanged(int block) {
     }
 
     /**
      * Notify possible subclass that a read cmd is being handled
+     * @param block - something about a block
      */
     public void noteReadCmd(int block) {
     }
 
     /**
      * Notify possible subclass that a read reply is being handled
+     * @param block - something about a block
      */
     public void noteReadReply(int block) {
     }
 
     /**
      * Notify possible subclass that a write operation is complete
+     * @param block - something about a block
      */
     public void noteWriteComplete(int block) {
     }
@@ -235,6 +239,7 @@ public void noteWriteComplete(int block) {
      * <p>
      * If we're not an image, we just sent this, so we'll ignore it.
      *
+     * @param msg a LocoNet message
      */
     void readMsg(LocoNetMessage msg) {
         // sort out the ATASK

java/src/jmri/jmrix/loconet/LnClockControl.java

@@ -47,14 +47,18 @@ public class LnClockControl extends DefaultClockControl implements SlotListener
 
     /**
      * Create a ClockControl object for a Loconet clock
+     * @param scm - the LocoNet System Connection Memo to associate with this
+     *              Clock Control object
      */
     public LnClockControl(LocoNetSystemConnectionMemo scm) {
         this(scm.getSlotManager(), scm.getLnTrafficController(), scm.getPowerManager());
     }
-    
+
     /**
      * Create a ClockControl object for a Loconet clock
      * @deprecated 4.11.5
+     * @param sm the Slot Manager associated with this object
+     * @param tc the Traffic Controller associated with this object
      */
     @Deprecated // 4.11.5
     public LnClockControl(SlotManager sm, LnTrafficController tc) {
@@ -63,14 +67,17 @@ public LnClockControl(SlotManager sm, LnTrafficController tc) {
 
     /**
      * Create a ClockControl object for a Loconet clock
+     * @param sm the Slot Manager associated with this object
+     * @param tc the Traffic Controller associated with this object
+     * @param pm the Power Manager associated with this object
      */
     public LnClockControl(SlotManager sm, LnTrafficController tc, LnPowerManager pm) {
         super();
 
         this.sm = sm;
         this.tc = tc;
         this.pm = pm;
-        
+
         // listen for updated slot contents
         if (sm != null) {
             sm.addSlotListener(this);
@@ -118,6 +125,7 @@ public void propertyChange(java.beans.PropertyChangeEvent e) {
 
     /**
      * Accessor routines
+     * @return the associated name
      */
     @Override
     public String getHardwareClockName() {
@@ -269,6 +277,7 @@ public void newMinute() {
      * responding to a read from this module 3) a slot not involving the clock
      * changing
      *
+     * @param s the LocoNetSlot object which has been changed
      */
     @SuppressWarnings("deprecation")
     @Override
@@ -321,7 +330,7 @@ else if ((temRate != curRate) && setInternal) {
             // unsolicited time change from the Loconet
             clock.setTime(new Date(nNumMSec));
         }
-        // Once we have done everything else set the flag to say we are in sync 
+        // Once we have done everything else set the flag to say we are in sync
         inSyncWithInternalFastClock = true;
     }
 
@@ -332,14 +341,14 @@ private void setClock() {
         if (setInternal || synchronizeWithInternalClock || correctFastClock) {
             // we are allowed to send commands to the fast clock
             LocoNetSlot s = sm.slot(LnConstants.FC_SLOT);
-            
+
             // load time
             s.setFcDays(curDays);
             s.setFcHours(curHours);
             s.setFcMinutes(curMinutes);
             s.setFcRate(curRate);
             s.setFcFracMins(curFractionalMinutes);
-            
+
             // set other content
             //     power (GTRK_POWER, 0x01 bit in byte 7)
             boolean power = true;
@@ -350,7 +359,7 @@ private void setClock() {
             }
             s.setTrackStatus(s.getTrackStatus() &  (~LnConstants.GTRK_POWER) );
             if (power) s.setTrackStatus(s.getTrackStatus() | LnConstants.GTRK_POWER);
-            
+
             // and write
             tc.sendLocoNetMessage(s.writeSlot());
         }
@@ -372,4 +381,3 @@ public void dispose() {
     private final static Logger log = LoggerFactory.getLogger(LnClockControl.class);
 
 }
-

java/src/jmri/jmrix/loconet/LnCommandStationType.java

@@ -83,6 +83,7 @@ public String getName() {
 
     /**
      * Can this command station read back from decoders?
+     * @return whether the command station can perform CV reads
      */
     public boolean getCanRead() {
         return canRead;
@@ -95,6 +96,7 @@ public String toString() {
 
     /**
      * Does a programming operation turn track power off?
+     * @return whether the programming operation turns track power off
      */
     public boolean getProgPowersOff() {
         return progEndOp;
@@ -111,6 +113,9 @@ static public LnCommandStationType getByName(String name) {
 
     /**
      * Get a new ThrottleManager of the right type for this command station.
+     * 
+     * @param memo the LocoNetSystemConnectionMemo object which hosts throttles
+     * @return the ThrottleManager object for the connection and the command station
      */
     public ThrottleManager getThrottleManager(LocoNetSystemConnectionMemo memo) {
         try {
@@ -141,6 +146,9 @@ public ThrottleManager getThrottleManager(LocoNetSystemConnectionMemo memo) {
 
     /**
      * Get a new SlotManager of the right type for this command station.
+     * 
+     * @param tc the LnTrafficController object which hosts the slot manager
+     * @return the SlogManager object for the connection and the command station
      */
     public SlotManager getSlotManager(LnTrafficController tc) {
         try {

java/src/jmri/jmrix/loconet/LnLight.java

@@ -17,6 +17,10 @@ public class LnLight extends AbstractLight {
      * Create a Light object, with only system name.
      * <p>
      * 'systemName' was previously validated in LnLightManager
+     * 
+     * @param systemName for the new bean
+     * @param tc the LnTrafficController which handles the messaging
+     * @param mgr the LnLightManager which manages this type of object bean
      */
     public LnLight(String systemName, LnTrafficController tc, LnLightManager mgr) {
         super(systemName);
@@ -30,6 +34,11 @@ public LnLight(String systemName, LnTrafficController tc, LnLightManager mgr) {
      * Create a Light object, with both system and user names.
      * <p>
      * 'systemName' was previously validated in LnLightManager
+     * 
+     * @param systemName for the new bean
+     * @param userName for the new bean
+     * @param tc the LnTrafficController which handles the messaging
+     * @param mgr the LnLightManager which manages this type of object bean
      */
     public LnLight(String systemName, String userName, LnTrafficController tc, LnLightManager mgr) {
         super(systemName, userName);

java/src/jmri/jmrix/loconet/LnLightManager.java

@@ -58,6 +58,8 @@ public Light createNewLight(String systemName, String userName) {
 
     /**
      * Get the bit address from the system name.
+     * @param systemName the systemName to be checked for validity
+     * @return the bit address number from the system name
      */
     public int getBitFromSystemName(String systemName) {
         // validate the system Name leader characters
@@ -89,8 +91,9 @@ public int getBitFromSystemName(String systemName) {
     /**
      * Validate system name format.
      *
-     * @return 'true' if system name has a valid format,
-     * else returns 'false'
+     * @param systemName the systemName to be validated
+     * @return NameValidity.VALID if system name has a valid format,
+     * else returns NameValidity.INVALID
      */
     @Override
     public NameValidity validSystemNameFormat(String systemName) {
@@ -101,6 +104,7 @@ public NameValidity validSystemNameFormat(String systemName) {
      * Validate system name for configuration.
      * Needed for the Abstract Light class.
      *
+     * @param systemName the systemName to be validated
      * @return 'true' if system name has a valid meaning in current configuration,
      * else returns 'false'. For now this method always returns 'true';
      */
@@ -113,6 +117,8 @@ public boolean validSystemNameConfig(String systemName) {
      * Determine if it is possible to add a range of Lights in
      * numerical order eg. 11 thru 18, primarily used to show/not show the add
      * range box in the Add Light pane.
+     * @param systemName - an ignored parameter
+     * @return true, always
      */
     @Override
     public boolean allowMultipleAdditions(String systemName) {

java/src/jmri/jmrix/loconet/LnOpsModeProgrammer.java

@@ -42,6 +42,10 @@ public LnOpsModeProgrammer(LocoNetSystemConnectionMemo memo,
 
     /**
      * @deprecated 4.13.6 Use LnOpsModeProgrammer(LocoNetSystemConnectionMemo memo, int, bool) instead
+     * @param pSlotMgr the slot manager for this programmer
+     * @param memo the memo for this programmer
+     * @param pAddress the decoder address to be programmed
+     * @param pLongAddr true if pAddress represents a DCC "Long" address
      */
     @Deprecated // 4.13.6 Use LnOpsModeProgrammer(LocoNetSystemConnectionMemo memo, int, bool) instead
     public LnOpsModeProgrammer(SlotManager pSlotMgr,

java/src/jmri/jmrix/loconet/LnPacketizer.java

@@ -116,7 +116,7 @@ public void sendLocoNetMessage(LocoNetMessage m) {
         try {
             synchronized (xmtHandler) {
                 xmtList.addLast(msg);
-                xmtHandler.notify(); 
+                xmtHandler.notifyAll(); 
             }
         } catch (RuntimeException e) {
             log.warn("passing to xmit: unexpected exception: ", e);

java/src/jmri/jmrix/loconet/LnPortController.java

@@ -80,13 +80,15 @@ public boolean okToSend() {
     // and "PR2 standalone programmer" in pr2/Pr2Adaper
     /**
      * Set config info from a name, which needs to be one of the valid ones.
+     * @param name the name of the command station type
      */
     public void setCommandStationType(String name) {
         setCommandStationType(LnCommandStationType.getByName(name));
     }
 
     /**
      * Set config info from the command station type enum.
+     * @param value the LnCommandStationType
      */
     public void setCommandStationType(LnCommandStationType value) {
         if (value == null) {

java/src/jmri/jmrix/loconet/LnPr2ThrottleManager.java

@@ -21,6 +21,7 @@ public class LnPr2ThrottleManager extends AbstractThrottleManager {
 
     /**
      * Constructor, works via superclass.
+     * @param memo the LocoNetSystemConnectionMemo
      */
     public LnPr2ThrottleManager(LocoNetSystemConnectionMemo memo) {
         super(memo);
@@ -100,6 +101,7 @@ static boolean isLongAddress(int num) {
     /**
      * Make the active address available to the power manager, which needs it to
      * turn on and off "neutral mode" in the locomotive
+     * @return a DccLocoAddress
      */
     public DccLocoAddress getActiveAddress() {
         return activeAddress;

java/src/jmri/jmrix/loconet/LnProgrammerManager.java

@@ -21,6 +21,8 @@ public LnProgrammerManager(LocoNetSystemConnectionMemo memo) {
 
     /**
      * @deprecated 4.13.6 Use LnProgrammerManager(LocoNetSystemConnectionMemo memo) instead
+     * @param pSlotManager - an ignored parameter
+     * @param memo the LocoNetSystemConnectionMemo to associate with this manager
      */
     @Deprecated // 4.13.6 Use LnProgrammerManager(LocoNetSystemConnectionMemo memo) instead
     public LnProgrammerManager(SlotManager pSlotManager, LocoNetSystemConnectionMemo memo) {

java/src/jmri/jmrix/loconet/LnSensorAddress.java

@@ -115,7 +115,11 @@ void reportParseError(String s) {
 
     /**
      * Update a LocoNet message to have this address.
+     * 
+     * It is assumed that the sensor address may be encoded into bytes 1 and 2 of the 
+     * message.
      *
+     * @param m a LocoNetmessage to be updated to contain this object's sensor address
      */
     public void insertAddress(LocoNetMessage m) {
         m.setElement(1, getLowBits());

java/src/jmri/jmrix/loconet/LnSensorManager.java

@@ -172,6 +172,8 @@ public String createSystemName(String curAddress, String prefix) throws JmriExce
 
     /**
      * Get the bit address from the system name.
+     * @param systemName a valid LocoNet-based Sensor System Name
+     * @return the sensor number extracted from the system name
      */
     public int getBitFromSystemName(String systemName) {
         // validate the system Name leader characters

java/src/jmri/jmrix/loconet/LnTurnoutManager.java

@@ -199,6 +199,8 @@ public NameValidity validSystemNameFormat(String systemName) {
 
     /**
      * Get the bit address from the system name.
+     * @param systemName a valid LocoNet-based Turnout System Name
+     * @return the turnout number extracted from the system name
      */
     public int getBitFromSystemName(String systemName) {
         // validate the system Name leader characters

java/src/jmri/jmrix/loconet/LocoNetConsistManager.java

@@ -23,6 +23,7 @@ public class LocoNetConsistManager extends AbstractConsistManager {
      * consist reader thread, which retrieves consist information from the
      * command station
      *
+     * @param lm the LocoNetSystemConnectionMemo to which this object is related
      */
     public LocoNetConsistManager(LocoNetSystemConnectionMemo lm) {
         super();

java/src/jmri/jmrix/loconet/LocoNetMessage.java

@@ -91,6 +91,7 @@ public LocoNetMessage(int len) {
      * this method of AbstractMessage is not supported.
      * <p>
      * This constructor always logs an error
+     * @param s an unused parameter
      */
     public LocoNetMessage(String s) {
         _nDataChars = 0;

java/src/jmri/jmrix/loconet/Pr2Throttle.java

@@ -24,6 +24,8 @@ public class Pr2Throttle extends AbstractThrottle {
 
     /**
      * Constructor
+     * @param memo a LocoNetSystemConnectionMemo to associate with this throttle
+     * @param address a DccLocoAddress to associate with this throttle
      */
     public Pr2Throttle(LocoNetSystemConnectionMemo memo, DccLocoAddress address) {
         super(memo);

java/src/jmri/jmrix/loconet/UhlenbrockSlot.java

@@ -28,6 +28,7 @@ public UhlenbrockSlot(LocoNetMessage l) throws LocoNetException {
      * Load functions 9 through 12 from LocoNet Uhlenbrock Intellibox-II
      * implementation to be used only for message with Op code
      * RE_OPC_IB2_F9_F12.
+     * @param m a LocoNet message which contains an iB2 "function control" message.
      */
     public void iB2functionMessage(LocoNetMessage m) {
         // parse for F9-12 functions
@@ -43,6 +44,7 @@ public void iB2functionMessage(LocoNetMessage m) {
      * Load functions 9 through 28 from LocoNet Uhlenbrock Intellibox-I and -II
      * implementation to be used only for message with Op code
      * RE_OPC_IB2_SPECIAL.
+     * @param m a LocoNet message which contains an iB "function control" message.
      */
     public void iBfunctionMessage(LocoNetMessage m) {
         // parse for which set of functions

java/src/jmri/jmrix/loconet/locobuffer/ConnectionConfig.java

@@ -11,6 +11,7 @@ public class ConnectionConfig extends jmri.jmrix.AbstractSerialConnectionConfig
     /**
      * Ctor for an object being created during load process; Swing init is
      * deferred.
+     * @param p the SerialPortAdapter to associate with this connection
      */
     public ConnectionConfig(jmri.jmrix.SerialPortAdapter p) {
         super(p);

java/src/jmri/jmrix/loconet/locobufferii/ConnectionConfig.java

@@ -11,6 +11,7 @@ public class ConnectionConfig extends jmri.jmrix.AbstractSerialConnectionConfig
     /**
      * Ctor for an object being created during load process; Swing init is
      * deferred.
+     * @param p the SerialPortAdapter to associate with this connection
      */
     public ConnectionConfig(jmri.jmrix.SerialPortAdapter p) {
         super(p);

java/src/jmri/jmrix/loconet/locobufferusb/ConnectionConfig.java

@@ -13,6 +13,7 @@ public class ConnectionConfig extends jmri.jmrix.AbstractSerialConnectionConfig
     /**
      * Ctor for an object being created during load process; Swing init is
      * deferred.
+     * @param p the SerialPortAdapter to associate with this connection
      */
     public ConnectionConfig(jmri.jmrix.SerialPortAdapter p) {
         super(p);

java/src/jmri/jmrix/loconet/loconetovertcp/ConnectionConfig.java

@@ -14,6 +14,7 @@ public class ConnectionConfig extends jmri.jmrix.AbstractNetworkConnectionConfig
     /**
      * Ctor for an object being created during load process; Swing init is
      * deferred.
+     * @param p the NetworkPortAdapter to associate with this connection
      */
     public ConnectionConfig(jmri.jmrix.NetworkPortAdapter p) {
         super(p);