diff --git a/src/main/java/de/ids_mannheim/korap/query/DistanceConstraint.java b/src/main/java/de/ids_mannheim/korap/query/DistanceConstraint.java
index 6a0668f..0bb3e43 100644
--- a/src/main/java/de/ids_mannheim/korap/query/DistanceConstraint.java
+++ b/src/main/java/de/ids_mannheim/korap/query/DistanceConstraint.java
@@ -1,10 +1,49 @@
 package de.ids_mannheim.korap.query;
 
 /**
- * Specify distance constraints in SpanDistanceQueries or
- * SpanMultipleDistanceQueries
+ * DistanceConstraint specifies the constraints used in
+ * {@link SpanDistanceQueries} or {@link SpanMultipleDistanceQueries}. The
+ * constraints comprise the distance unit, the minimum and maximum distance, the
+ * order and the co-occurence of the compared spans.
  * 
+ * Distance constraint examples:
  * 
+ * <ol>
+ * <li>Two terms x and y are separated by minimum two and maximum three other
+ * words. The order of x and y does not matter.
+ * 
+ * <pre>
+ * DistanceConstraint dc = new DistanceConstraint(2, 3, false, false);
+ * </pre>
+ * 
+ * </li>
+ * <li>Two terms x and y are separated by minimum two and maximum three other
+ * words. X must precede y.
+ * 
+ * <pre>
+ * DistanceConstraint dc = new DistanceConstraint(2, 3, true, false);
+ * </pre>
+ * 
+ * </li>
+ * <li>
+ * Term x do not occur with term y in minimum two and maximum three other words.
+ * X must precede y.
+ * 
+ * <pre>
+ * DistanceConstraint dc = new DistanceConstraint(2, 3, true, true);
+ * </pre>
+ * 
+ * </li>
+ * <li>Two terms x and y separated by minimum one and maximum two
+ * <em>sentences</em>. X must precede y.
+ * 
+ * <pre>
+ * SpanElementQuery e = new SpanElementQuery(&quot;tokens&quot;, &quot;s&quot;);
+ * DistanceConstraint dc = new DistanceConstraint(e, 2, 3, true, false);
+ * </pre>
+ * 
+ * </li>
+ * </ol>
  * 
  * @author margaretha
  * */
diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanDistanceQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanDistanceQuery.java
index 87616c9..d8083c6 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanDistanceQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanDistanceQuery.java
@@ -18,144 +18,252 @@
 import de.ids_mannheim.korap.query.spans.UnorderedElementDistanceSpans;
 import de.ids_mannheim.korap.query.spans.UnorderedTokenDistanceSpans;
 
-/** Match two ordered or unordered spans with some minimum and maximum 
- * 	distance constraints. The distance unit can be word (token), 
- * 	sentence or paragraph. The distance can also be specified to match 
- * 	some spans which do <em>not</em> co-occur with some other Spans within a min 
- * 	and max distance. 
+/**
+ * SpanDistanceQuery calculates the distance between two spans and compares it
+ * to the distance constraints. The distance constraints are specified as a
+ * {@link DistanceConstraint} instance having various properties: the distance
+ * unit, the order of the spans (ordered or unordered), co-occurrence (i.e. the
+ * spans should co-occur or not), minimum and maximum distance. <br/>
+ * <br/>
+ * The distance unit can be word (token), sentence or paragraph. The resulting
+ * spans typically stretch from the starting position of a former span to the
+ * end position of the latter span. <br/>
+ * <br/>
+ * Query examples:
  * 
- * 	@author margaretha
+ * <ol>
+ * <li>Search two terms x and y which are separated by minimum two and maximum
+ * three other words. The order of x and y does not matter.
+ * 
+ * <pre>
+ * DistanceConstraint dc = new DistanceConstraint(2, 3, false, false);
+ * </pre>
+ * 
+ * </li>
+ * <li>Search two terms x and y which are separated by minimum two and maximum
+ * three other words. X must precede y.
+ * 
+ * <pre>
+ * DistanceConstraint dc = new DistanceConstraint(2, 3, true, false);
+ * </pre>
+ * 
+ * </li>
+ * <li>
+ * Search term x which do not occur with term y in minimum two and maximum three
+ * other words. X must precede y.
+ * 
+ * <pre>
+ * DistanceConstraint dc = new DistanceConstraint(2, 3, true, true);
+ * </pre>
+ * 
+ * </li>
+ * <li>Search two terms x and y separated by minimum one and maximum two
+ * sentences. X must precede y.
+ * 
+ * <pre>
+ * SpanElementQuery e = new SpanElementQuery(&quot;tokens&quot;, &quot;s&quot;);
+ * DistanceConstraint dc = new DistanceConstraint(e, 2, 3, true, false);
+ * </pre>
+ * 
+ * </li>
+ * </ol>
+ * 
+ * SpanDistanceQuery examples:
+ * 
+ * <ol>
+ * <li>
+ * 
+ * <pre>
+ * SpanDistanceQuery sq = new SpanDistanceQuery(new SpanTermQuery(new Term(
+ *         &quot;tokens&quot;, x)), new SpanTermQuery(new Term(&quot;tokens&quot;, y)), dc, true);
+ * </pre>
+ * 
+ * </li>
+ * <li>
+ * 
+ * <pre>
+ * SpanDistanceQuery sq = new SpanDistanceQuery(
+ *         new SpanElementQuery(&quot;tokens&quot;, &quot;s&quot;), new SpanElementQuery(&quot;tokens&quot;, y),
+ *         dc, true);
+ * </pre>
+ * 
+ * </li>
+ * </ol>
+ * 
+ * 
+ * @author margaretha
  * */
 public class SpanDistanceQuery extends SimpleSpanQuery {
-	
-	private boolean exclusion;
-	private boolean isOrdered;	
-	private int minDistance, maxDistance;	
-	private SpanElementQuery elementQuery; // element distance unit (sentence or paragraph)
-	private String distanceUnit;
-	private String spanName;
-	private DistanceConstraint constraint;
 
-	public SpanDistanceQuery(SpanQuery firstClause, SpanQuery secondClause, 
-			DistanceConstraint constraint, boolean collectPayloads) {
-		super(firstClause, secondClause, collectPayloads);
-		
-		if (constraint == null){
-			throw new IllegalArgumentException("Distance constraint cannot be null.");
-		}
-		
-		this.constraint = constraint;
-		this.minDistance = constraint.getMinDistance();
-		this.maxDistance = constraint.getMaxDistance();
-		this.isOrdered = constraint.isOrdered();
-		this.exclusion = constraint.isExclusion();
-		this.distanceUnit = constraint.getUnit();
-		
-		if (constraint.getElementQuery() != null){
-			spanName = "spanElementDistance";
-			this.elementQuery = constraint.getElementQuery();
-		}
-		else { spanName = "spanDistance"; }
-	}
-	
-	@Override
-	public String toString(String field) {
-		StringBuilder sb = new StringBuilder();
-		sb.append(this.spanName);
-		sb.append("(");
-		sb.append(firstClause.toString(field));
-	    sb.append(", ");
-		sb.append(secondClause.toString(field));
-		sb.append(", ");
-		sb.append("[(");
-		sb.append(distanceUnit);
-		sb.append("[");
-		sb.append(minDistance);
-		sb.append(":");
-		sb.append(maxDistance);
-		sb.append("], ");		
-		sb.append( isOrdered ? "ordered, " : "notOrdered, " );
-		sb.append( exclusion ? "excluded)])" : "notExcluded)])");
-		sb.append(ToStringUtils.boost(getBoost()));
-    	return sb.toString();
+    private boolean exclusion;
+    private boolean isOrdered;
+    private int minDistance, maxDistance;
+    private SpanElementQuery elementQuery; // element distance unit (sentence or
+                                           // paragraph)
+    private String distanceUnit;
+    private String spanName;
+    private DistanceConstraint constraint;
+
+    /**
+     * Constructs a SpanDistanceQuery comparing the distance between the spans
+     * of the two specified spanqueries and based-on the given distance
+     * constraints.
+     * 
+     * */
+    public SpanDistanceQuery(SpanQuery firstClause, SpanQuery secondClause,
+            DistanceConstraint constraint, boolean collectPayloads) {
+        super(firstClause, secondClause, collectPayloads);
+
+        if (constraint == null) {
+            throw new IllegalArgumentException(
+                    "Distance constraint cannot be null.");
+        }
+
+        this.constraint = constraint;
+        this.minDistance = constraint.getMinDistance();
+        this.maxDistance = constraint.getMaxDistance();
+        this.isOrdered = constraint.isOrdered();
+        this.exclusion = constraint.isExclusion();
+        this.distanceUnit = constraint.getUnit();
+
+        if (constraint.getElementQuery() != null) {
+            spanName = "spanElementDistance";
+            this.elementQuery = constraint.getElementQuery();
+        } else {
+            spanName = "spanDistance";
+        }
     }
-	
-	@Override
-	public SpanDistanceQuery clone() {		
-		SpanDistanceQuery spanDistanceQuery = new SpanDistanceQuery(
-		    (SpanQuery) firstClause.clone(),
-		    (SpanQuery) secondClause.clone(),
-		    this.constraint,
-		    this.collectPayloads
-        );
-				
-		if (this.elementQuery != null) {
-			spanDistanceQuery.setElementQuery(this.elementQuery);
-		}
-		spanDistanceQuery.setBoost(getBoost());
-		return spanDistanceQuery;	
-	}
 
-	@Override
-	public Spans getSpans(AtomicReaderContext context, Bits acceptDocs,
-			Map<Term, TermContext> termContexts) throws IOException {		
-		
-		if (this.elementQuery != null) {
-			if (isExclusion()){
-				return new ElementDistanceExclusionSpans(this, context, acceptDocs, 
-						termContexts, isOrdered);
-			}			
-			else if (isOrdered){
-				return new ElementDistanceSpans(this, context, acceptDocs, 
-						termContexts);
-			}
-			return new UnorderedElementDistanceSpans(this, context, acceptDocs, 
-					termContexts);
-			
-		}
-		else if (isExclusion()){
-			return new DistanceExclusionSpans(this, context, acceptDocs, 
-					termContexts, isOrdered);
-		}
-		else if (isOrdered) {
-			return new TokenDistanceSpans(this, context, acceptDocs, 
-					termContexts);		
-		}
-		return new UnorderedTokenDistanceSpans(this, context, acceptDocs, 
-				termContexts);
-	}
+    @Override
+    public String toString(String field) {
+        StringBuilder sb = new StringBuilder();
+        sb.append(this.spanName);
+        sb.append("(");
+        sb.append(firstClause.toString(field));
+        sb.append(", ");
+        sb.append(secondClause.toString(field));
+        sb.append(", ");
+        sb.append("[(");
+        sb.append(distanceUnit);
+        sb.append("[");
+        sb.append(minDistance);
+        sb.append(":");
+        sb.append(maxDistance);
+        sb.append("], ");
+        sb.append(isOrdered ? "ordered, " : "notOrdered, ");
+        sb.append(exclusion ? "excluded)])" : "notExcluded)])");
+        sb.append(ToStringUtils.boost(getBoost()));
+        return sb.toString();
+    }
 
-	public int getMinDistance() {
-		return minDistance;
-	}
+    @Override
+    public SpanDistanceQuery clone() {
+        SpanDistanceQuery spanDistanceQuery = new SpanDistanceQuery(
+                (SpanQuery) firstClause.clone(),
+                (SpanQuery) secondClause.clone(), this.constraint,
+                this.collectPayloads);
 
-	public void setMinDistance(int minDistance) {
-		this.minDistance = minDistance;
-	}
+        if (this.elementQuery != null) {
+            spanDistanceQuery.setElementQuery(this.elementQuery);
+        }
+        spanDistanceQuery.setBoost(getBoost());
+        return spanDistanceQuery;
+    }
 
-	public int getMaxDistance() {
-		return maxDistance;
-	}
+    @Override
+    public Spans getSpans(AtomicReaderContext context, Bits acceptDocs,
+            Map<Term, TermContext> termContexts) throws IOException {
 
-	public void setMaxDistance(int maxDistance) {
-		this.maxDistance = maxDistance;
-	}
-	
-	public SpanElementQuery getElementQuery() {
-		return elementQuery;
-	}
-	
-	public void setElementQuery(SpanElementQuery elementQuery) {
-		this.elementQuery = elementQuery;
-	}
+        if (this.elementQuery != null) {
+            if (isExclusion()) {
+                return new ElementDistanceExclusionSpans(this, context,
+                        acceptDocs, termContexts, isOrdered);
+            } else if (isOrdered) {
+                return new ElementDistanceSpans(this, context, acceptDocs,
+                        termContexts);
+            }
+            return new UnorderedElementDistanceSpans(this, context, acceptDocs,
+                    termContexts);
 
-	public boolean isExclusion() {
-		return exclusion;
-	}
+        } else if (isExclusion()) {
+            return new DistanceExclusionSpans(this, context, acceptDocs,
+                    termContexts, isOrdered);
+        } else if (isOrdered) {
+            return new TokenDistanceSpans(this, context, acceptDocs,
+                    termContexts);
+        }
+        return new UnorderedTokenDistanceSpans(this, context, acceptDocs,
+                termContexts);
+    }
 
-	public void setExclusion(boolean exclusion) {
-		this.exclusion = exclusion;
-	}
+    /**
+     * Returns the minimum distance constraint
+     * 
+     * @return minimum distance constraint
+     */
+    public int getMinDistance() {
+        return minDistance;
+    }
 
+    /**
+     * Sets the minimum distance constraint
+     * 
+     * @param minDistance
+     */
+    public void setMinDistance(int minDistance) {
+        this.minDistance = minDistance;
+    }
+
+    /**
+     * Returns the maximum distance constraint
+     * 
+     * @return maximum distance constraint
+     */
+    public int getMaxDistance() {
+        return maxDistance;
+    }
+
+    /**
+     * Sets a maximum distance constraint
+     * 
+     * @param maxDistance
+     */
+    public void setMaxDistance(int maxDistance) {
+        this.maxDistance = maxDistance;
+    }
+
+    /**
+     * Returns the element query used as the distance unit
+     * 
+     * @return the element distance unit
+     */
+    public SpanElementQuery getElementQuery() {
+        return elementQuery;
+    }
+
+    /**
+     * Sets the specified element query used for the distance unit
+     * 
+     * @param elementQuery
+     */
+    public void setElementQuery(SpanElementQuery elementQuery) {
+        this.elementQuery = elementQuery;
+    }
+
+    /**
+     * Tells weather the second sub-span should co-occur or not.
+     * */
+    public boolean isExclusion() {
+        return exclusion;
+    }
+
+    /**
+     * Sets true if the second sub-span should <em>not</em> co-occur.
+     * 
+     * @param exclusion
+     */
+    public void setExclusion(boolean exclusion) {
+        this.exclusion = exclusion;
+    }
 
 }