add javadoc

jsprit-core/src/main/java/jsprit/core/problem/job/Job.java

@@ -16,10 +16,28 @@
  ******************************************************************************/
 package jsprit.core.problem.job;
 
+/**
+ * Basic interface for all jobs.
+ * 
+ * @author schroeder
+ *
+ */
 public interface Job {
 
+	/**
+	 * Returns the unique identifier (id) of a job.
+	 * 
+	 * @return id
+	 */
 	public String getId();
 
+	/**
+	 * Returns capacity (demand) of job.
+	 * 
+	 * <p>It determines how much capacity this job consumes of vehicle/transport unit.
+	 * 
+	 * @return
+	 */
 	public int getCapacityDemand();
 	
 	

jsprit-core/src/main/java/jsprit/core/problem/job/Service.java

@@ -19,55 +19,133 @@ package jsprit.core.problem.job;
 import jsprit.core.problem.solution.route.activity.TimeWindow;
 import jsprit.core.util.Coordinate;
 
-
+/**
+ * Service implementation of a job.
+ * 
+ * <p>A service distinguishes itself from a shipment such that it has only one locations. Thus a service
+ * is a single point in space (where a service-activity occurs).
+ * 
+ * <p>Note that two services are equal if they have the same id.
+ * 
+ * @author schroeder
+ *
+ */
 public class Service implements Job {
 
+	/**
+	 * Builder that builds a service.
+	 * 
+	 * @author schroeder
+	 *
+	 */
 	public static class Builder {
 		
+		/**
+		 * Returns a new instance of service-builder.
+		 * 
+		 * @param id of service
+		 * @param size of capacity-demand
+		 * @return builder
+		 */
 		public static Builder newInstance(String id, int size){
 			return new Builder(id,size);
 		}
 		
 		private String id;
+		
 		protected String locationId;
+		
 		private String type = "service";
+		
 		protected Coordinate coord;
+		
 		protected double serviceTime;
+		
 		protected TimeWindow timeWindow = TimeWindow.newInstance(0.0, Double.MAX_VALUE);
+		
 		protected int demand;
 		
+		/**
+		 * Constructs the builder.
+		 * 
+		 * @param id
+		 * @param size
+		 */
 		Builder(String id, int size) {
 			if(size < 0) throw new IllegalArgumentException("size must be greater than or equal to zero");
 			this.id = id;
 			this.demand = size;
 		}
 		
+		/**
+		 * Protected method to set the type-name of the service.
+		 * 
+		 * <p>Currently there are {@link Service}, {@link Pickup} and {@link Delivery}.
+		 * 
+		 * @param name
+		 * @return the builder
+		 */
 		protected Builder setType(String name){
 			this.type = name;
 			return this;
 		}
 		
+		/**
+		 * Sets the location-id of this service.
+		 * 
+		 * @param locationId
+		 * @return builder
+		 */
 		public Builder setLocationId(String locationId){
 			this.locationId = locationId;
 			return this;
 		}
 		
+		/**
+		 * Sets the coordinate of this service.
+		 * 
+		 * @param coord
+		 * @return builder
+		 */
 		public Builder setCoord(Coordinate coord){
 			this.coord = coord;
 			return this;
 		}
 		
+		/**
+		 * Sets the serviceTime of this service.
+		 * 
+		 * <p>It is understood as time that a service or its implied activity takes at the service-location, for instance
+		 * to unload goods.
+		 * 
+		 * @param serviceTime
+		 * @return builder
+		 */
 		public Builder setServiceTime(double serviceTime){
 			if(serviceTime < 0) throw new IllegalArgumentException("serviceTime must be greate than or equal to zero");
 			this.serviceTime = serviceTime;
 			return this;
 		}
 		
+		/**
+		 * Sets the time-window of this service.
+		 * 
+		 * <p>The time-window indicates the time period a service/activity/operation is allowed to start. 
+		 * 
+		 * @param tw
+		 * @return builder
+		 */
 		public Builder setTimeWindow(TimeWindow tw){
 			this.timeWindow = tw;
 			return this;
 		}
 		
+		/**
+		 * Builds the service.
+		 * 
+		 * @return {@link Service}
+		 * @throws IllegalStateException if neither locationId nor coordinate is set.
+		 */
 		public Service build(){
 			if(locationId == null) { 
 				if(coord == null) throw new IllegalStateException("either locationId or a coordinate must be given. But is not.");
@@ -109,18 +187,38 @@ public class Service implements Job {
 		return id;
 	}
 
+	/**
+	 * Returns the location-id of this service.
+	 * 
+	 * @return String that indicates the location
+	 */
 	public String getLocationId() {
 		return locationId;
 	}
 	
+	/**
+	 * Returns the coordinate of this service.
+	 * 
+	 * @return {@link Coordinate}
+	 */
 	public Coordinate getCoord(){
 		return coord;
 	}
 
+	/**
+	 * Returns the service-time/duration a service takes at service-location.
+	 * 
+	 * @return service duration
+	 */
 	public double getServiceDuration() {
 		return serviceTime;
 	}
 
+	/**
+	 * Returns the time-window a service(-operation) is allowed to start.
+	 * 
+	 * @return time window
+	 */
 	public TimeWindow getTimeWindow(){
 		return timeWindow;
 	}
@@ -137,14 +235,17 @@ public class Service implements Job {
 		return type;
 	}
 
+	/**
+	 * Returns a string with the service's attributes.
+	 * 
+	 * <p>String is built as follows: [attr1=val1][attr2=val2]...
+	 */
 	@Override
 	public String toString() {
 		return "[id=" + id + "][type="+type+"][locationId=" + locationId + "][coord="+coord+"][size=" + demand + "][serviceTime=" + serviceTime + "][timeWindow=" + timeWindow + "]";
 	}
 
-	/* (non-Javadoc)
+
-	 * @see java.lang.Object#hashCode()
-	 */
 	@Override
 	public int hashCode() {
 		final int prime = 31;
@@ -153,8 +254,9 @@ public class Service implements Job {
 		return result;
 	}
 
-	/* (non-Javadoc)
+	/**
-	 * @see java.lang.Object#equals(java.lang.Object)
+	 * Two services are equal if they have the same id.
+	 * 
 	 */
 	@Override
 	public boolean equals(Object obj) {