improved documentation

examples/src/OpenDis7Examples/ExampleSimulationProgram.java

@@ -18,23 +18,30 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /** The purpose of this program is to provide an easily modifiable example simulation program
- *  that includes DIS-capable entities doing tasks and reporting them. */
+ *  that includes DIS-capable entities doing tasks and reporting them to the network.
+ *  Default settings include PDU recording turned on by default.
+ */
 public class ExampleSimulationProgram
 {
     /**
-     * runSimulation is for you! This block is programmer-modifiable method for defining and running a new simulation of interest.
+     * This runSimulation() method is for you! This block is programmer-modifiable method 
+     * for defining and running a new simulation of interest.
      * Support include DIS EntityStatePdu, FirePdu and CommentPdu all available for 
      * modification and sending in a simulation loop.
+     * Continuous improvement efforts seek to make this program as easy and straightforward
+     * as possible for new simulationists to use and adapt.
+     * All of the other methods are setup, teardown and configuration that you don't have to worry about.
      */
     @SuppressWarnings("SleepWhileInLoop")
     public void runSimulation ()
     {
       try
       {
-        final double LOOP_DURATION_SECONDS  =  1.0; // seconds
-        final int    MAX_LOOP_COUNT = 10;
-              int    loopCount = 0;
-        boolean simulationComplete = false; // sentinel variable as termination condition
+        /** seconds for real-time execution (not simulation time, which may or may not be the same) */
+        final double LOOP_DURATION_SECONDS  =  1.0; 
+        final int    MAX_LOOP_COUNT = 10;   // be deliberate out out there!
+              int    loopCount = 0;         // initialized at 0
+        boolean simulationComplete = false; // sentinel variable as termination condition,, are we done yet?
         
         // TODO reset clock to zero each time for consistent outputs
         
@@ -42,7 +49,8 @@ public class ExampleSimulationProgram
         // create PDU objects and set their values
         
         EntityID       entityID_1    = new EntityID();
-        entityID_1.setSiteID(1).setApplicationID(2).setEntityID(3); // made-up example ID
+        entityID_1.setSiteID(1).setApplicationID(2).setEntityID(3); // made-up example ID; 
+        // TODO use enumerations; is there a unique site triplet for MOVES Institute?
 
         EntityStatePdu entityStatePdu = pduFactory.makeEntityStatePdu();
         entityStatePdu.setEntityID(entityID_1);
@@ -53,17 +61,18 @@ public class ExampleSimulationProgram
         // TODO simulation management PDUs for startup
         
         // loop the simulation while allowed, programmer can set additional conditions to break out and finish
-        while (loopCount < MAX_LOOP_COUNT) 
+        while (loopCount < MAX_LOOP_COUNT)  // are we done yet?
         {
-            // initialize loop variables
-            loopCount++;
+            loopCount++; // good practice: increment loop counter as first action
             
             // =============================================================================================
             // your own simulation code starts here!
             
+            //  are there any other variables to modify at the beginning of your loop?
+            
             // compute a track, update an ESPDU, whatever it is that your model is doing...
             
-            // Where is my entity?
+            // Where is my entity?  Insert changes in position.
             entityStatePdu.getEntityLocation().setX(entityStatePdu.getEntityLocation().getX() + 1.0); // 1m per timestep
             
             // decide whether to fire, and then update the firePdu.  Hmmm, you might want a target to shoort at!
@@ -156,7 +165,7 @@ public class ExampleSimulationProgram
     }
     
     /**
-     * Utility Constructor
+     * Utility Constructor that allows your example simulation program to override default network address and port
      * @param address network address to use
      * @param port corresponding network port to use
      */
@@ -180,7 +189,7 @@ public class ExampleSimulationProgram
      */
     public final void setNetworkAddress(String newNetworkAddress)
     {
-        this.networkAddress = newNetworkAddress;
+        ExampleSimulationProgram.networkAddress = newNetworkAddress;
     }
 
     /**
@@ -196,7 +205,7 @@ public class ExampleSimulationProgram
      */
     public final void setNetworkPort(int newNetworkPort)
     {
-        this.networkPort = newNetworkPort;
+        ExampleSimulationProgram.networkPort = newNetworkPort;
     }
 
     /**