improved comments

examples/src/OpenDis7Examples/ExampleSimulationProgram.java

 /**
  * Copyright (c) 2008-2021, MOVES Institute, Naval Postgraduate School (NPS). All rights reserved.
  * This work is provided under a BSD open-source license, see project license.html and license.txt
+ * @author brutzman@nps.edu
  */
 package OpenDis7Examples;
 
@@ -24,60 +25,66 @@ import java.util.logging.Logger;
 public class ExampleSimulationProgram
 {
     /**
-     * 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 
+     * This runSimulation() method is for you, a
+     * programmer-modifiable method for defining and running a new simulation of interest.
+     * Welcome! Other parts of this program handle bookkeeping and plumbing tasks so that
+     * you can focus on your model entities and activities.
+     * Expandable support includes 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.
+     * as possible for DIS simulationists to use and adapt.
+     * All of the other methods are setup, teardown and configuration that you may find
+     * interesting, even helpful, but don't really have to worry about.
      */
-    @SuppressWarnings("SleepWhileInLoop")
+    @SuppressWarnings("SleepWhileInLoop") // yes we do that
     public void runSimulation ()
     {
       try
       {
         /** 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?
+        final double  SIMULATION_LOOP_DURATION_SECONDS  =  1.0; 
+        final int     SIMULATION_MAX_LOOP_COUNT = 10; // be deliberate out out there!  also avoid infinite loops.
+              int     simulationLoopCount = 0;        // variable, 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
         
-        // your model setup: who's who in this zoo?
-        // create PDU objects and set their values
+        // Your model setup: define participants.  who's who in this zoo?
+        // Assuming you keep track of entity objects...  here is some support for for Entity 1.
         
+        // create PDU objects and set their values.
         EntityID       entityID_1    = new EntityID();
         entityID_1.setSiteID(1).setApplicationID(2).setEntityID(3); // made-up example ID; 
-        // TODO use enumerations; is there a unique site triplet for MOVES Institute?
+        // TODO someday, use enumerations; is there a unique site triplet for MOVES Institute?
 
-        EntityStatePdu entityStatePdu = pduFactory.makeEntityStatePdu();
-        entityStatePdu.setEntityID(entityID_1);
+        EntityStatePdu entityStatePdu_1 = pduFactory.makeEntityStatePdu();
+        entityStatePdu_1.setEntityID(entityID_1);
 
-        FirePdu               firePdu = pduFactory.makeFirePdu();
+        FirePdu        firePdu_1a       = pduFactory.makeFirePdu(); // for entity 1 first  weapon (if any)
+        FirePdu        firePdu_1b       = pduFactory.makeFirePdu(); // for entity 1 second weapon (if any)
         // should we customize this munition?  what is it for your simulation?
         
-        // TODO simulation management PDUs for startup
+        // TODO simulation management PDUs for startup, planning to design special class support
         
         // loop the simulation while allowed, programmer can set additional conditions to break out and finish
-        while (loopCount < MAX_LOOP_COUNT)  // are we done yet?
+        while (simulationLoopCount < SIMULATION_MAX_LOOP_COUNT)  // are we done yet?
         {
-            loopCount++; // good practice: increment loop counter as first action
+            simulationLoopCount++; // good practice: increment loop counter as first action in that loop
             
             // =============================================================================================
-            // your own simulation code starts here!
+            // * 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?  Insert changes in position.
-            entityStatePdu.getEntityLocation().setX(entityStatePdu.getEntityLocation().getX() + 1.0); // 1m per timestep
-            
+            // Where is my entity?  Insert changes in position; this sample only changes X position.
+            entityStatePdu_1.getEntityLocation().setX(entityStatePdu_1.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!
             
-            // etc. etc. your code goes here
+            // etc. etc. your code goes here for your simulation of interest
                 
             // something happens between my simulation entities, la de da de da...
             System.out.println ("... My simulation just did something, no really...");
@@ -85,37 +92,38 @@ public class ExampleSimulationProgram
             
             // make your reports: narrative code for CommentPdu here (set all to empty strings to avoid sending)
             narrativeMessage1 = "MV3500 ExampleSimulationProgram";
-            narrativeMessage2 = "runSimulation() loop " + loopCount;
+            narrativeMessage2 = "runSimulation() loop " + simulationLoopCount;
             narrativeMessage3 = ""; // intentionally blank for testing
 
             // your loop termination condition goes here
-            if (loopCount > 4) // for example
+            if (simulationLoopCount > 4) // for example
             {
                 simulationComplete = true;
             }      
-            // your own simulation code is finished here!
+            // =============================================================================================
+            // * your own simulation code is finished here! *
             // =============================================================================================
             
-            // keep track of timestep: wait duration for elapsed time in this loop
+            // staying synchronized with timestep: wait duration for elapsed time in this loop
             // Thread.sleep needs a (long) parameter for milliseconds, which are clumsy to use sometimes
-            Thread.sleep((long)(LOOP_DURATION_SECONDS * 1000)); // seconds * (1000 msec/sec) = milliseconds
-            System.out.println ("... [Pausing for " + LOOP_DURATION_SECONDS + " seconds]");
+            Thread.sleep((long)(SIMULATION_LOOP_DURATION_SECONDS * 1000)); // seconds * (1000 msec/sec) = milliseconds
+            System.out.println ("... [Pausing for " + SIMULATION_LOOP_DURATION_SECONDS + " seconds]");
             
-            // send the status PDUs for this loop and continue
-            System.out.println ("sending PDUs for simulation step " + loopCount + ", monitor loopback to confirm sent");
-            sendAllPdusForLoopTimestep(entityStatePdu, firePdu, timeStepComment, narrativeMessage1, narrativeMessage2, narrativeMessage3);
+            // OK now send the status PDUs for this loop, and then continue
+            System.out.println ("sending PDUs for simulation step " + simulationLoopCount + ", monitor loopback to confirm sent");
+            sendAllPdusForLoopTimestep(entityStatePdu_1, firePdu_1a, timeStepComment, narrativeMessage1, narrativeMessage2, narrativeMessage3);
             System.out.println ("... [PDUs successfully sent for this loop]");
             
             // ===============================
-            // loop now finished, thus terminate if simulation complete, otherwise send latest PDUs and continue
-            if (simulationComplete || (loopCount > 10000)) // for example; including fail-safe condition is good
+            // loop now finished, check whether to terminate if simulation complete, otherwise continue
+            if (simulationComplete || (simulationLoopCount > 10000)) // for example; including fail-safe condition is good
             {
                 System.out.println ("... [Termination condition met, simulationComplete=" + simulationComplete + "]"); // ", final loopCount=" + loopCount + 
                 break;
             }
-        }   // end of while loop
-        // all done
-        narrativeMessage2 = "runSimulation() completed successfully";
+        }   // end of simulation loop
+        
+        narrativeMessage2 = "runSimulation() completed successfully"; // all done
         sendCommentPdu(narrativeComment, narrativeMessage1, narrativeMessage2, narrativeMessage3);
         System.out.println ("... [final CommentPdu successfully sent for simulation]");
         // TODO simulation management PDUs
@@ -133,6 +141,7 @@ public class ExampleSimulationProgram
     String narrativeMessage3 = new String();
           
     /* VariableRecordType enumerations have potential use with CommentPdu logs */
+    /* TODO contrast to EntityType */
     VariableRecordType descriptionComment = VariableRecordType.DESCRIPTION;
     VariableRecordType   narrativeComment = VariableRecordType.COMPLETE_EVENT_REPORT;
     VariableRecordType      statusComment = VariableRecordType.APPLICATION_STATUS;