Checkstyle

src/edu/kit/informatik/modelrailwaysimulator/model/ModelRailwaySimulation.java

@@ -13,7 +13,16 @@ import java.util.stream.Collectors;
 import java.util.stream.IntStream;
 
 /**
- * Model railway simulation. Can simulate trains on a railway network.
+ * Model railway simulation. Can simulate trains moving on a railway network. Features:
+ * <ul>
+ *     <li>allows creating different types of rolling stock: engines, train-sets and coaches</li>
+ *     <li>handles both straight tracks and switches</li>
+ *     <li>only supports deterministic rail networks</li>
+ *     <li>trains can be composed of many rolling stocks</li>
+ *     <li>fancy ASCII art of trains can be generated</li>
+ *     <li>collision checking is slightly simplified and operates on a rail-based model</li>
+ *     <li>large railway networks can be simulated quickly</li>
+ * </ul>
  *
  * @author Arne Keller
  * @version 1.0
@@ -88,7 +97,7 @@ public class ModelRailwaySimulation {
     }
 
     /**
-     * Change the setting of a switch in the rail network.
+     * Change the setting of a switch in the rail network. Will derail trains on that switch.
      *
      * @param id identifier of the switch
      * @param position position to set the switch to
@@ -103,6 +112,8 @@ public class ModelRailwaySimulation {
     }
 
     /**
+     * Add a new engine to the simulation.
+     *
      * @param newEngine the engine to add to the simulation
      * @throws InvalidInputException when the identifier is already in use
      */
@@ -247,7 +258,8 @@ public class ModelRailwaySimulation {
      * @param trainId identifier of the train
      * @param rollingStockId identifier of the rolling stock
      * @return the added rolling stock
-     * @throws InvalidInputException if input is incorrect
+     * @throws InvalidInputException if train not found and train identifier is not next identifier or rolling stock
+     *  is not found
      */
     public RollingStock addTrain(int trainId, String rollingStockId) throws InvalidInputException {
         final Optional<RollingStock> rollingStock = getRollingStock(rollingStockId);
@@ -305,7 +317,8 @@ public class ModelRailwaySimulation {
      * @param position where to place the train
      * @param direction direction in which the train should initially go
      * @return whether the train was successfully placed
-     * @throws InvalidInputException e.g. when the train is too long or direction is invalid
+     * @throws InvalidInputException if train could not be found, is already placed, is not valid, direction is invalid
+     *  or railway network is not ready for trains
      */
     public boolean putTrain(int trainId, Vector2D position, Vector2D direction) throws InvalidInputException {
         return trainManager.putTrain(trainId, position, direction);

src/edu/kit/informatik/modelrailwaysimulator/model/RailwayNetwork.java

@@ -155,8 +155,8 @@ public class RailwayNetwork {
     }
 
     /**
-     * Get a sorted list of all rails in the network, specifying their identifier, start and end points, their length
+     * Get a sorted list of all rails in the network, specifying their type, identifier, start and end points and
-     * and their current configuration.
+     * their length.
      *
      * @return list of rails
      */

src/edu/kit/informatik/modelrailwaysimulator/model/TrainManager.java

@@ -113,7 +113,7 @@ public final class TrainManager {
      * Delete a train. Will not delete rolling stock contained in that train.
      *
      * @param trainId identifier of the train
-     * @return whether the train could be deleted
+     * @return whether the train could be deleted (false if not found)
      */
     public boolean deleteTrain(int trainId) {
         final Train train = trains.get(trainId);
@@ -158,7 +158,8 @@ public final class TrainManager {
      * @param position where to place the train
      * @param direction direction in which the train should initially go
      * @return whether the train was successfully placed
-     * @throws InvalidInputException if train could not be placed due to semantic error
+     * @throws InvalidInputException if train could not be found, is already placed, is not valid, direction is invalid
+     *  or railway network is not ready for trains
      */
     public boolean putTrain(int trainId, Vector2D position, Vector2D direction) throws InvalidInputException {
         final Train train = trains.get(trainId);

testcoverage_output.txt

@@ -171,9 +171,9 @@ OK
 diesel engine T5-Hartnick added to train 6
 OK
 Crash of train 6
-Error, switch has length zero
+Error, switch endpoint would connect to two other rails
-Error, switch has length zero
+Error, switch endpoint would connect to two other rails
-Error, switch has length zero
+Error, switch endpoint would connect to two other rails
 OK
 OK
 OK