diff --git a/jsprit-core/src/main/java/jsprit/core/algorithm/VariablePlusFixedSolutionCostCalculatorFactory.java b/jsprit-core/src/main/java/jsprit/core/algorithm/VariablePlusFixedSolutionCostCalculatorFactory.java
index 77f890c1..7a35ecaa 100644
--- a/jsprit-core/src/main/java/jsprit/core/algorithm/VariablePlusFixedSolutionCostCalculatorFactory.java
+++ b/jsprit-core/src/main/java/jsprit/core/algorithm/VariablePlusFixedSolutionCostCalculatorFactory.java
@@ -6,6 +6,14 @@ import jsprit.core.problem.solution.route.VehicleRoute;
 import jsprit.core.problem.solution.route.state.RouteAndActivityStateGetter;
 import jsprit.core.problem.solution.route.state.StateFactory;
 
+/**
+ * Default objective function which is the sum of all fixed vehicle and variable
+ * transportation costs, i.e. each is generated solution is evaluated according
+ * this objective function.
+ * 
+ * @author schroeder
+ *
+ */
 public class VariablePlusFixedSolutionCostCalculatorFactory {
 	
 	private RouteAndActivityStateGetter stateManager;
diff --git a/jsprit-core/src/main/java/jsprit/core/algorithm/VehicleRoutingAlgorithmBuilder.java b/jsprit-core/src/main/java/jsprit/core/algorithm/VehicleRoutingAlgorithmBuilder.java
index d402f168..7d813cdf 100644
--- a/jsprit-core/src/main/java/jsprit/core/algorithm/VehicleRoutingAlgorithmBuilder.java
+++ b/jsprit-core/src/main/java/jsprit/core/algorithm/VehicleRoutingAlgorithmBuilder.java
@@ -9,6 +9,12 @@ import jsprit.core.problem.VehicleRoutingProblem;
 import jsprit.core.problem.constraint.ConstraintManager;
 import jsprit.core.problem.solution.SolutionCostCalculator;
 
+/**
+ * Builder that builds a {@link VehicleRoutingAlgorithm}.
+ * 
+ * @author schroeder
+ *
+ */
 public class VehicleRoutingAlgorithmBuilder {
 
 	private final String algorithmConfig;
@@ -27,36 +33,92 @@ public class VehicleRoutingAlgorithmBuilder {
 
 	private int nuOfThreads=0;
 	
+	/**
+	 * Constructs the builder.
+	 * 
+	 * @param problem
+	 * @param algorithmConfig
+	 */
 	public VehicleRoutingAlgorithmBuilder(VehicleRoutingProblem problem, String algorithmConfig) {
 		this.vrp=problem;
 		this.algorithmConfig=algorithmConfig;
 	}
 
+	/**
+	 * Sets custom objective function. 
+	 * 
+	 * <p>If objective function is not set, a default function is applied (which basically minimizes 
+	 * fixed and variable transportation costs ({@link VariablePlusFixedSolutionCostCalculatorFactory}).
+	 * 
+	 * @param objectiveFunction
+	 * @see VariablePlusFixedSolutionCostCalculatorFactory
+	 */
 	public void setObjectiveFunction(SolutionCostCalculator objectiveFunction) {
 		this.solutionCostCalculator = objectiveFunction;
 	}
 
+	/**
+	 * Sets stateManager to memorize states.
+	 * 
+	 * @param stateManager
+	 * @see StateManager
+	 */
 	public void setStateManager(StateManager stateManager) {
 		this.stateManager=stateManager;
 	}
 
+	/**
+	 * Adds core constraints.
+	 * 
+	 * <p>Thus, it adds vehicle-capacity and time-window constraints and their 
+	 * required stateUpdater.
+	 * 
+	 */
 	public void addCoreConstraints() {
 		addCoreConstraints=true;
 	}
 
+	/**
+	 * Adds default cost calculators used by the insertion heuristic,
+	 * to calculate activity insertion costs.
+	 * By default, marginal transportation costs are calculated. Thus when inserting
+	 * act_k between act_i and act_j, marginal (additional) transportation costs
+	 * are basically c(act_i,act_k)+c(act_k,act_j)-c(act_i,act_j).
+	 * 
+	 * <p>Do not use this method, if you plan to control the insertion heuristic
+	 * entirely via hard- and soft-constraints.
+	 */
 	public void addDefaultCostCalculators() {
 		addDefaultCostCalculators=true;
 	}
 
+	/**
+	 * Sets state- and constraintManager. 
+	 * 
+	 * @param stateManager
+	 * @param constraintManager
+	 * @see StateManager
+	 * @see ConstraintManager
+	 */
 	public void setStateAndConstraintManager(StateManager stateManager, ConstraintManager constraintManager) {
 		this.stateManager=stateManager;
 		this.constraintManager=constraintManager;
 	}
 	
+	/**
+	 * Sets nuOfThreads.
+	 * 
+	 * @param nuOfThreads
+	 */
 	public void setNuOfThreads(int nuOfThreads){
 		this.nuOfThreads=nuOfThreads;
 	}
 
+	/**
+	 * Builds and returns the algorithm.
+	 * 
+	 * @return
+	 */
 	public VehicleRoutingAlgorithm build() {
 		if(stateManager == null) stateManager = new StateManager(vrp.getTransportCosts());
 		if(constraintManager == null) constraintManager = new ConstraintManager(vrp,stateManager,vrp.getConstraints());
diff --git a/jsprit-core/src/main/java/jsprit/core/algorithm/state/StateManager.java b/jsprit-core/src/main/java/jsprit/core/algorithm/state/StateManager.java
index 416c476d..37125436 100644
--- a/jsprit-core/src/main/java/jsprit/core/algorithm/state/StateManager.java
+++ b/jsprit-core/src/main/java/jsprit/core/algorithm/state/StateManager.java
@@ -51,7 +51,7 @@ import jsprit.core.problem.solution.route.state.StateFactory.StateId;
  * Manages states.
  * 
  * <p>Some condition, rules or constraints are stateful. This StateManager manages these states, i.e. it offers
- * methods to add, store and retrieve states based on vehicle-routes and tour-activities.
+ * methods to add, store and retrieve states based on the problem, vehicle-routes and tour-activities.
  * 
  * @author schroeder
  *
diff --git a/jsprit-core/src/main/java/jsprit/core/problem/constraint/ConstraintManager.java b/jsprit-core/src/main/java/jsprit/core/problem/constraint/ConstraintManager.java
index fd6545c4..3e0113a4 100644
--- a/jsprit-core/src/main/java/jsprit/core/problem/constraint/ConstraintManager.java
+++ b/jsprit-core/src/main/java/jsprit/core/problem/constraint/ConstraintManager.java
@@ -13,7 +13,12 @@ import jsprit.core.problem.solution.route.state.RouteAndActivityStateGetter;
 
 import org.apache.log4j.Logger;
 
-@SuppressWarnings("deprecation")
+/**
+ * Manager that manage hard- and soft constraints, both on route and activity level.
+ * 
+ * @author schroeder
+ *
+ */
 public class ConstraintManager implements HardActivityStateLevelConstraint, HardRouteStateLevelConstraint, SoftActivityConstraint, SoftRouteConstraint{
 
 	public static enum Priority {