add javadoc (feature #127)

jsprit-core/src/main/java/jsprit/core/problem/misc/JobInsertionContext.java

@@ -31,6 +31,9 @@ import java.util.List;
  */
 public class JobInsertionContext {
 
+    /**
+     * Provides insertion context information about a particular activity.
+     */
     public static class ActivityContext {
 
         private double arrivalTime;
@@ -39,26 +42,66 @@ public class JobInsertionContext {
 
         private int insertionIndex;
 
+        /**
+         * Returns arrival time at associated activity.
+         *
+         * @return arrival time
+         */
         public double getArrivalTime() {
             return arrivalTime;
         }
 
+        /**
+         * Returns end time of associated activity.
+         *
+         * @return end time
+         */
         public double getEndTime() {
             return endTime;
         }
 
+        /**
+         * Returns the insertion index of the associated vehicle.
+         *
+         * <p>The associated activity is not inserted yet. The actual insertion position is still to be evaluated.
+         * Thus this insertion index is related to the potential insertion index which is the position before
+         * the activity at this index in the existing route.
+         *
+         * if insertionIndex == 0, the associated activity will be inserted between start of vehicle and the first
+         * activity in activity sequence.
+         *
+         * if insertionIndex == relatedRoute.getActivities().size(), the associated activity will be inserted between
+         * the last activity in the activity sequence and the end of vehicle.
+         *
+         * @return insertion index
+         */
         public int getInsertionIndex() {
             return insertionIndex;
         }
 
+        /**
+         * Sets arrivalTime of associated vehicle at activity.
+         *
+         * @param arrivalTime arrival time of associated vehicle at activity
+         */
         public void setArrivalTime(double arrivalTime) {
             this.arrivalTime = arrivalTime;
         }
 
+        /**
+         * Sets end time of associated activity.
+         *
+         * @param endTime end time
+         */
         public void setEndTime(double endTime) {
             this.endTime = endTime;
         }
 
+        /**
+         * Sets insertion index of associated activity.
+         *
+         * @param insertionIndex insertion index of associated activity
+         */
         public void setInsertionIndex(int insertionIndex) {
             this.insertionIndex = insertionIndex;
         }