diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanSegmentQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanSegmentQuery.java
index 0c25081..286e239 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanSegmentQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanSegmentQuery.java
@@ -13,71 +13,96 @@
 
 import de.ids_mannheim.korap.query.spans.SegmentSpans;
 
-/** Matching two spans having exactly the same start and end positions.
- * @author margaretha 
+/**
+ * SpanSegmentQuery matches two spans having exactly the same start and end
+ * positions, for instance:
+ * 
+ * <pre>
+ * sq = new SpanSegmentQuery(
+            new SpanTermQuery(new Term("tokens","s:Hund")),
+            new SpanTermQuery(new Term("tokens","tt/p:NN"))
+       );
+ * </pre>
+ * @author margaretha
  * */
-public class SpanSegmentQuery extends SimpleSpanQuery{
-	
-	public SpanSegmentQuery(SpanQuery firstClause, SpanQuery secondClause) {
-		this(firstClause,secondClause,true);
-	}
-	
-	public SpanSegmentQuery(SpanQuery firstClause, SpanQuery secondClause, 
-			boolean collectPayloads) { 
-    	super(firstClause,secondClause,collectPayloads);
-	}
-	
-	@Override
-	public Spans getSpans(AtomicReaderContext context, Bits acceptDocs, 
-			Map<Term, TermContext> termContexts) throws IOException {
-		return (Spans) new SegmentSpans(this, context, acceptDocs,
-				termContexts);
-	}		
-	
-	@Override
-	public SpanSegmentQuery clone() {
-		SpanSegmentQuery spanSegmentQuery = new SpanSegmentQuery(
-		    (SpanQuery) firstClause.clone(),
-		    (SpanQuery) secondClause.clone(),
-		    collectPayloads
-        );
-		spanSegmentQuery.setBoost(getBoost());
-		return spanSegmentQuery;		
-	}
-	
-    @Override
-	public String toString(String field) {
-		StringBuilder sb = new StringBuilder();
-		sb.append("spanSegment(");
-		sb.append(firstClause.toString(field));
-        sb.append(", ");
-		sb.append(secondClause.toString(field));
-		sb.append(")");
-		sb.append(ToStringUtils.boost(getBoost()));
-		return sb.toString();	
+public class SpanSegmentQuery extends SimpleSpanQuery {
+
+    /**
+     * Creates a SpanSegmentQuery from the two given SpanQueries, by default
+     * payloads are to be collected.
+     * 
+     * @param firstClause a {@link SpanQuery}
+     * @param secondClause a {@link SpanQuery}
+     */
+    public SpanSegmentQuery(SpanQuery firstClause, SpanQuery secondClause) {
+        this(firstClause, secondClause, true);
     }
-	
+
+    /**
+     * @param firstClause a {@link SpanQuery}
+     * @param secondClause a {@link SpanQuery}
+     * @param collectPayloads a boolean flag representing the value
+     *        <code>true</code> if payloads are to be collected, otherwise
+     *        <code>false</code>.
+     */
+    public SpanSegmentQuery(SpanQuery firstClause, SpanQuery secondClause,
+            boolean collectPayloads) {
+        super(firstClause, secondClause, collectPayloads);
+    }
+
+    @Override
+    public Spans getSpans(AtomicReaderContext context, Bits acceptDocs,
+            Map<Term, TermContext> termContexts) throws IOException {
+        return (Spans) new SegmentSpans(this, context, acceptDocs, termContexts);
+    }
+
+    @Override
+    public SpanSegmentQuery clone() {
+        SpanSegmentQuery spanSegmentQuery = new SpanSegmentQuery(
+                (SpanQuery) firstClause.clone(),
+                (SpanQuery) secondClause.clone(), collectPayloads);
+        spanSegmentQuery.setBoost(getBoost());
+        return spanSegmentQuery;
+    }
+
+    @Override
+    public String toString(String field) {
+        StringBuilder sb = new StringBuilder();
+        sb.append("spanSegment(");
+        sb.append(firstClause.toString(field));
+        sb.append(", ");
+        sb.append(secondClause.toString(field));
+        sb.append(")");
+        sb.append(ToStringUtils.boost(getBoost()));
+        return sb.toString();
+    }
+
     @Override
     public boolean equals(Object o) {
-		if (this == o) return true;
-		if (!(o instanceof SpanSegmentQuery)) return false;
-		
-		SpanSegmentQuery spanSegmentQuery = (SpanSegmentQuery) o;
-		
-		if (collectPayloads != spanSegmentQuery.collectPayloads) return false;
-		if (!firstClause.equals(spanSegmentQuery.firstClause)) return false;
-		if (!secondClause.equals(spanSegmentQuery.secondClause)) return false;
-	
-		return getBoost() == spanSegmentQuery.getBoost();
+        if (this == o)
+            return true;
+        if (!(o instanceof SpanSegmentQuery))
+            return false;
+
+        SpanSegmentQuery spanSegmentQuery = (SpanSegmentQuery) o;
+
+        if (collectPayloads != spanSegmentQuery.collectPayloads)
+            return false;
+        if (!firstClause.equals(spanSegmentQuery.firstClause))
+            return false;
+        if (!secondClause.equals(spanSegmentQuery.secondClause))
+            return false;
+
+        return getBoost() == spanSegmentQuery.getBoost();
     };
 
     @Override
     public int hashCode() {
-		int result;
-		result = firstClause.hashCode() + secondClause.hashCode();
-		result ^= (31 * result) + (result >>> 3);
-		result += Float.floatToRawIntBits(getBoost());
-		return result;
+        int result;
+        result = firstClause.hashCode() + secondClause.hashCode();
+        result ^= (31 * result) + (result >>> 3);
+        result += Float.floatToRawIntBits(getBoost());
+        return result;
     };
 
 }
diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanSubspanQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanSubspanQuery.java
index a1aed2e..2cba5d9 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanSubspanQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanSubspanQuery.java
@@ -12,67 +12,109 @@
 
 import de.ids_mannheim.korap.query.spans.SubSpans;
 
-/**	This query extracts a subspan from a span. The subspan starts from 
- * 	a startOffset until startOffset + length. A positive startOffset 
- * 	is counted from the start of the span, while a negative startOffset 
- * 	is counted from the end of the span. 
+/**
+ * This query extracts a subspan from another span. The subspan starts from a
+ * startOffset until startOffset + length. A positive startOffset is counted
+ * from the start of the span, while a negative startOffset is counted from the
+ * end of the span. <br />
+ * <br />
+ * SpanSubspanQuery takes a SpanQuery as its input and creates subspans from the
+ * resulting spans of the SpanQuery. For instance:
  * 
- * 	@author margaretha
+ * <pre>
+ * SpanTermQuery stq = new SpanTermQuery(new Term("tokens","s:Hund"))
+ * SpanSubspanQuery ssq = new SpanSubspanQuery(stq, 0, 2, true);
+ * </pre>
+ * 
+ * In this example, the SpanSubspanQuery creates subspans "Hu" from all the
+ * occurrences of TermSpans "Hund", that starts from index 0 to 2. It also
+ * collects all payloads from the TermSpans for the SubSpans.
+ * 
+ * @author margaretha
  * */
-public class SpanSubspanQuery extends SimpleSpanQuery{
-	
-	private int startOffset, length;
-			
-	public SpanSubspanQuery(SpanQuery firstClause, int startOffset, int length, 
-			boolean collectPayloads) {
-		super(firstClause, collectPayloads);
-		this.startOffset = startOffset;
-		this.length = length;
-	}
+public class SpanSubspanQuery extends SimpleSpanQuery {
 
-	@Override
-	public SimpleSpanQuery clone() {
-		SpanSubspanQuery sq = new SpanSubspanQuery(
-				this.getFirstClause(), 
-				this.startOffset,
-				this.length, 
-				this.collectPayloads);
-		sq.setBoost(this.getBoost());
-		return sq;
-	}
+    private int startOffset, length;
 
-	@Override
-	public Spans getSpans(AtomicReaderContext context, Bits acceptDocs,
-			Map<Term, TermContext> termContexts) throws IOException {
-		return new SubSpans(this, context, acceptDocs, termContexts);
-	}
+    /**
+     * Creates a SpanSubspanQuery (subspan) from the given {@link SpanQuery}
+     * with the specified startOffset and length.
+     * 
+     * @param firstClause a SpanQuery
+     * @param startOffset the start offset of the subspan relative to the
+     *        original span
+     * @param length the length of the subspan
+     * @param collectPayloads a boolean flag representing the value
+     *        <code>true</code> if payloads are to be collected, otherwise
+     *        <code>false</code>.
+     */
+    public SpanSubspanQuery(SpanQuery firstClause, int startOffset, int length,
+            boolean collectPayloads) {
+        super(firstClause, collectPayloads);
+        this.startOffset = startOffset;
+        this.length = length;
+    }
 
-	@Override
-	public String toString(String field) {		
-		StringBuilder sb = new StringBuilder();
-		sb.append("subspan(");
-		sb.append(this.firstClause.toString());
-		sb.append(",");
-		sb.append(this.startOffset);
-		sb.append(",");
-		sb.append(this.length);
-		sb.append(")");
-		return sb.toString();
-	}
+    @Override
+    public SimpleSpanQuery clone() {
+        SpanSubspanQuery sq = new SpanSubspanQuery(this.getFirstClause(),
+                this.startOffset, this.length, this.collectPayloads);
+        sq.setBoost(this.getBoost());
+        return sq;
+    }
 
-	public int getStartOffset() {
-		return startOffset;
-	}
+    @Override
+    public Spans getSpans(AtomicReaderContext context, Bits acceptDocs,
+            Map<Term, TermContext> termContexts) throws IOException {
+        return new SubSpans(this, context, acceptDocs, termContexts);
+    }
 
-	public void setStartOffset(int startOffset) {
-		this.startOffset = startOffset;
-	}
+    @Override
+    public String toString(String field) {
+        StringBuilder sb = new StringBuilder();
+        sb.append("subspan(");
+        sb.append(this.firstClause.toString());
+        sb.append(",");
+        sb.append(this.startOffset);
+        sb.append(",");
+        sb.append(this.length);
+        sb.append(")");
+        return sb.toString();
+    }
 
-	public int getLength() {
-		return length;
-	}
+    /**
+     * Returns the start offset.
+     * 
+     * @return the start offset.
+     */
+    public int getStartOffset() {
+        return startOffset;
+    }
 
-	public void setLength(int length) {
-		this.length = length;
-	}
+    /**
+     * Sets the start offset.
+     * 
+     * @param startOffset the start offset
+     */
+    public void setStartOffset(int startOffset) {
+        this.startOffset = startOffset;
+    }
+
+    /**
+     * Returns the length of the subspan.
+     * 
+     * @return the length of the subspan
+     */
+    public int getLength() {
+        return length;
+    }
+
+    /**
+     * Sets the length of the subspan.
+     * 
+     * @param length the length of the subspan.
+     */
+    public void setLength(int length) {
+        this.length = length;
+    }
 }
diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanTermWithIdQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanTermWithIdQuery.java
index 114d882..fa70878 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanTermWithIdQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanTermWithIdQuery.java
@@ -10,14 +10,22 @@
 import org.apache.lucene.search.spans.Spans;
 import org.apache.lucene.util.Bits;
 
+import de.ids_mannheim.korap.query.spans.SpansWithId;
 import de.ids_mannheim.korap.query.spans.TermSpansWithId;
 
 /**
- * SpanTermWithIdQuery wraps the normal SpanTermQuery and retrieves TermSpans
- * with a spanid. It is used in other spanqueries requiring spans with id as
- * their child spans, for example span relation with variable query (
+ * SpanTermWithIdQuery wraps a SpanTermQuery retrieving TermSpans and add a
+ * spanid to the TermSpans. It is used in other spanqueries requiring spans with
+ * id as their child spans, for example in span relation with variable query (
  * {@link SpanRelationPartQuery}).
  * 
+ * <pre>
+ * SpanTermWithIdQuery sq = new SpanTermWithIdQuery(new Term("base","tt:p/NN"),true)
+ * </pre>
+ * 
+ * In this example, the SpanTermWithIdQuery retrieves {@link SpansWithId} for
+ * the Term "tt:p/NN".
+ * 
  * @author margaretha
  * */
 public class SpanTermWithIdQuery extends SpanWithIdQuery {
diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanWithAttributeQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanWithAttributeQuery.java
index d2e8e6f..65335f2 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanWithAttributeQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanWithAttributeQuery.java
@@ -20,7 +20,20 @@
 /**
  * Enumeration of spans (e.g. element or relation spans) having some specific
  * attribute(s) or <em>not</em> having some attribute(s). It is necessary that
- * the spans have ids to be able to identify to which span an attribute belongs.
+ * the spans have ids to be able to identify to which span an attribute belongs. <br />
+ * <br />
+ * 
+ * In the example below, the SpanWithAttributeQuery retrieves
+ * <code>&lt;div&gt;</code> elements having attributes
+ * <code>@:class=header</code>.
+ * 
+ * <pre>
+ * SpanAttributeQuery saq = new SpanAttributeQuery(new SpanTermQuery(new Term(
+ *         &quot;tokens&quot;, &quot;@:class=header&quot;)), true);
+ * SpanWithAttributeQuery sq = new SpanWithAttributeQuery(new SpanElementQuery(
+ *         &quot;tokens&quot;, &quot;div&quot;), saq, true);
+ * </pre>
+ * 
  * 
  * @author margaretha
  */
@@ -68,7 +81,9 @@
         return type;
     }
 
-    /** Sets the type of the query based of the class of the firstClause / first span.
+    /**
+     * Sets the type of the query based of the class of the firstClause / first
+     * span.
      * 
      */
     public void setType() {
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/NextSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/NextSpans.java
index 7ebbc46..182942a 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/NextSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/NextSpans.java
@@ -15,144 +15,173 @@
 
 import de.ids_mannheim.korap.query.SpanNextQuery;
 
-/**	NextSpans is an enumeration of Span matches, which ensures that  
- * 	a span is immediately followed by another span.
- *  
- *  Update: allow multiple matches at the same firstspan position
- *  
- * 	@author margaretha, diewald
+/**
+ * NextSpans is an enumeration of Span matches, which ensures that a span is
+ * immediately followed by another span.
+ * 
+ * The implementation allows multiple matches at the same firstspan position.
+ * 
+ * @author margaretha, diewald
  * */
-public class NextSpans extends SimpleSpans {	
-	
-	private List<CandidateSpan> matchList;
-	private List<CandidateSpan> candidateList;
-	private int candidateListDocNum;
-	private boolean hasMoreFirstSpan;
-	
-	private Logger log = LoggerFactory.getLogger(NextSpans.class);
+public class NextSpans extends SimpleSpans {
 
-    // This advices the java compiler to ignore all loggings
-    public static final boolean DEBUG = false;
+    private List<CandidateSpan> matchList;
+    private List<CandidateSpan> candidateList;
+    private int candidateListDocNum;
+    private boolean hasMoreFirstSpan;
 
-	
-    public NextSpans (SpanNextQuery spanNextQuery,
-		      AtomicReaderContext context,
-		      Bits acceptDocs,
-		      Map<Term,TermContext> termContexts) throws IOException {
-    	super(spanNextQuery, context, acceptDocs, termContexts);
-    	collectPayloads = spanNextQuery.isCollectPayloads();
-    	hasMoreSpans =  secondSpans.next();
-    	matchList = new ArrayList<>();
-		candidateList = new ArrayList<>();
+    private Logger log = LoggerFactory.getLogger(NextSpans.class);
+
+    /**
+     * Constructs NextSpans for the given {@link SpanNextQuery}.
+     * 
+     * @param spanNextQuery
+     * @param context
+     * @param acceptDocs
+     * @param termContexts
+     * @throws IOException
+     */
+    public NextSpans(SpanNextQuery spanNextQuery, AtomicReaderContext context,
+            Bits acceptDocs, Map<Term, TermContext> termContexts)
+            throws IOException {
+        super(spanNextQuery, context, acceptDocs, termContexts);
+        collectPayloads = spanNextQuery.isCollectPayloads();
+        hasMoreSpans = secondSpans.next();
+        matchList = new ArrayList<>();
+        candidateList = new ArrayList<>();
     }
 
-	@Override
-	public boolean next() throws IOException {		
-		isStartEnumeration=false;
-  		matchPayload.clear();
-  		return advance();  		
-	}
-	
-	private boolean advance() throws IOException {
-		
-		while (hasMoreSpans || !matchList.isEmpty() || !candidateList.isEmpty()){			
-			if (!matchList.isEmpty()){
-				matchDocNumber = firstSpans.doc();
-			    matchStartPosition = firstSpans.start();
-			    matchEndPosition = matchList.get(0).getEnd();
-			    if (collectPayloads)
-			    	matchPayload.addAll( matchList.get(0).getPayloads() );	
-			    //System.out.println(this.toString());
-				/*System.out.println("Match positions "+ matchStartPosition+","+
-				  matchEndPosition);*/
-			    matchList.remove(0);
-			    return true;
-			}
-			// Forward firstspan
-			hasMoreFirstSpan = firstSpans.next();
-			if (hasMoreFirstSpan) setMatchList();
-			else {
-				hasMoreSpans = false;
-				candidateList.clear(); }
-		}		
-		return false;
-	}
+    @Override
+    public boolean next() throws IOException {
+        isStartEnumeration = false;
+        matchPayload.clear();
+        return advance();
+    }
 
-	private void setMatchList() throws IOException {
-		if (firstSpans.doc() == candidateListDocNum){			
-			searchCandidates();
-			searchMatches();
-		}
-		else{ 
-			candidateList.clear();
-			if (hasMoreSpans && ensureSameDoc(firstSpans,secondSpans)){
-				candidateListDocNum = firstSpans.doc();
-				searchMatches();				
-			}
-		}		
-	}
-	
-	private void searchCandidates() throws IOException {
-		Iterator<CandidateSpan> i = candidateList.iterator();
-		CandidateSpan cs;
-		while(i.hasNext()){
-			cs = i.next();
-			if (cs.getStart() == firstSpans.end()){
-				addMatch(cs);
-			}
-			else{
-				//System.out.println(cs.getStart() + " " +firstSpans.end());
-				i.remove();
-			}
-		}	
-	}
+    /**
+     * Advances the NextSpans to the next match by checking the matchList or
+     * setting the matchlist first, if it is empty.
+     * 
+     * @return <code>true</code> if a match is found, <code>false</code>
+     *         otherwise.
+     * @throws IOException
+     */
+    private boolean advance() throws IOException {
 
+        while (hasMoreSpans || !matchList.isEmpty() || !candidateList.isEmpty()) {
+            if (!matchList.isEmpty()) {
+                matchDocNumber = firstSpans.doc();
+                matchStartPosition = firstSpans.start();
+                matchEndPosition = matchList.get(0).getEnd();
+                if (collectPayloads)
+                    matchPayload.addAll(matchList.get(0).getPayloads());
+                //System.out.println(this.toString());
+                /*
+                 * System.out.println("Match positions "+
+                 * matchStartPosition+","+ matchEndPosition);
+                 */
+                matchList.remove(0);
+                return true;
+            }
+            // Forward firstspan
+            hasMoreFirstSpan = firstSpans.next();
+            if (hasMoreFirstSpan)
+                setMatchList();
+            else {
+                hasMoreSpans = false;
+                candidateList.clear();
+            }
+        }
+        return false;
+    }
 
-	private void searchMatches() throws IOException {
-		
-		while (hasMoreSpans && candidateListDocNum == secondSpans.doc()){
-			if (secondSpans.start() > firstSpans.end()){
-				break;
-			}
-			if (secondSpans.start() == firstSpans.end()){
-				candidateList.add(new CandidateSpan(secondSpans));
-				addMatch(new CandidateSpan(secondSpans));
-			}
-			hasMoreSpans = secondSpans.next();
-		}
-	}
-	
-	private void addMatch(CandidateSpan cs) throws IOException{
-		
-		int start = firstSpans.start();
-		long cost = firstSpans.cost() + cs.getCost();
-		
-		List<byte[]> payloads = new ArrayList<byte[]>();
-		if (collectPayloads) {
-			if (firstSpans.isPayloadAvailable())
-				payloads.addAll(firstSpans.getPayload());
-			if (cs.getPayloads() != null)
-				payloads.addAll(cs.getPayloads());
-		}	
-		
-		matchList.add(new CandidateSpan(start,cs.getEnd(),candidateListDocNum,cost,
-				payloads));
-	}
+    /**
+     * Sets the matchlist by first searching the candidates and then find all
+     * the matches.
+     * 
+     * @throws IOException
+     */
+    private void setMatchList() throws IOException {
+        if (firstSpans.doc() == candidateListDocNum) {
+            searchCandidates();
+            searchMatches();
+        } else {
+            candidateList.clear();
+            if (hasMoreSpans && ensureSameDoc(firstSpans, secondSpans)) {
+                candidateListDocNum = firstSpans.doc();
+                searchMatches();
+            }
+        }
+    }
 
-	@Override
-	public boolean skipTo(int target) throws IOException {
-		if (hasMoreSpans && (firstSpans.doc() < target)){
-  			if (!firstSpans.skipTo(target)){
-  				hasMoreSpans = false;
-  				return false;
-  			}			
-  		} 		
-  		matchPayload.clear();
-  		return advance();
-	}
+    /**
+     * Finds all candidates whose start position is the same as the firstspan's
+     * end position.
+     * 
+     * @throws IOException
+     */
+    private void searchCandidates() throws IOException {
+        Iterator<CandidateSpan> i = candidateList.iterator();
+        CandidateSpan cs;
+        while (i.hasNext()) {
+            cs = i.next();
+            if (cs.getStart() == firstSpans.end()) {
+                addMatch(cs);
+            } else {
+                //System.out.println(cs.getStart() + " " +firstSpans.end());
+                i.remove();
+            }
+        }
+    }
 
-	@Override
-	public long cost() {
-		return firstSpans.cost() + secondSpans.cost();
-	}
+    /**
+     * @throws IOException
+     */
+    private void searchMatches() throws IOException {
+
+        while (hasMoreSpans && candidateListDocNum == secondSpans.doc()) {
+            if (secondSpans.start() > firstSpans.end()) {
+                break;
+            }
+            if (secondSpans.start() == firstSpans.end()) {
+                candidateList.add(new CandidateSpan(secondSpans));
+                addMatch(new CandidateSpan(secondSpans));
+            }
+            hasMoreSpans = secondSpans.next();
+        }
+    }
+
+    private void addMatch(CandidateSpan cs) throws IOException {
+
+        int start = firstSpans.start();
+        long cost = firstSpans.cost() + cs.getCost();
+
+        List<byte[]> payloads = new ArrayList<byte[]>();
+        if (collectPayloads) {
+            if (firstSpans.isPayloadAvailable())
+                payloads.addAll(firstSpans.getPayload());
+            if (cs.getPayloads() != null)
+                payloads.addAll(cs.getPayloads());
+        }
+
+        matchList.add(new CandidateSpan(start, cs.getEnd(),
+                candidateListDocNum, cost, payloads));
+    }
+
+    @Override
+    public boolean skipTo(int target) throws IOException {
+        if (hasMoreSpans && (firstSpans.doc() < target)) {
+            if (!firstSpans.skipTo(target)) {
+                hasMoreSpans = false;
+                return false;
+            }
+        }
+        matchPayload.clear();
+        return advance();
+    }
+
+    @Override
+    public long cost() {
+        return firstSpans.cost() + secondSpans.cost();
+    }
 };
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/NonPartialOverlappingSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/NonPartialOverlappingSpans.java
index 4692da0..8e56ca7 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/NonPartialOverlappingSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/NonPartialOverlappingSpans.java
@@ -13,96 +13,114 @@
 
 import de.ids_mannheim.korap.query.SimpleSpanQuery;
 
-/** An abstract class for Span enumeration whose two child spans are matched by 
- * 	their positions and do not have a partial overlap.
- *  
- * 	@author margaretha  
+/**
+ * An abstract class for Span enumeration whose two child spans are matched by
+ * their positions and do not have a partial overlap.
+ * 
+ * @author margaretha
  * */
-public abstract class NonPartialOverlappingSpans extends SimpleSpans{
-	
-	private Logger log = LoggerFactory.getLogger(NonPartialOverlappingSpans.class);
+public abstract class NonPartialOverlappingSpans extends SimpleSpans {
 
-  	public NonPartialOverlappingSpans(SimpleSpanQuery simpleSpanQuery,
-			AtomicReaderContext context, Bits acceptDocs,
-			Map<Term,TermContext> termContexts) throws IOException {	    	  
-		super(simpleSpanQuery, context, acceptDocs, termContexts);
-		
-		// Warning: not implemented, results in errors for SpanNextQuery 
-		// This.collectPayloads = simpleSpanQuery.isCollectPayloads()
-		collectPayloads = true;
-		hasMoreSpans = secondSpans.next();		
-		
-	}
-	
+    private Logger log = LoggerFactory
+            .getLogger(NonPartialOverlappingSpans.class);
+
+    /**
+     * Constructs NonPartialOverlappingSpans from the given
+     * {@link SimpleSpanQuery}.
+     * 
+     * @param simpleSpanQuery a SimpleSpanQuery
+     * @param context
+     * @param acceptDocs
+     * @param termContexts
+     * @throws IOException
+     */
+    public NonPartialOverlappingSpans(SimpleSpanQuery simpleSpanQuery,
+            AtomicReaderContext context, Bits acceptDocs,
+            Map<Term, TermContext> termContexts) throws IOException {
+        super(simpleSpanQuery, context, acceptDocs, termContexts);
+
+        // Warning: not implemented, results in errors for SpanNextQuery 
+        // This.collectPayloads = simpleSpanQuery.isCollectPayloads()
+        collectPayloads = true;
+        hasMoreSpans = secondSpans.next();
+
+    }
+
     @Override
-  	public boolean next() throws IOException {
-    	// Warning: this does not work for overlapping spans 
-    	// e.g. get multiple second spans in a firstspan
-  		hasMoreSpans &= firstSpans.next();
-  		isStartEnumeration=false;
-  		matchPayload.clear();
-  		return advance();  		
-  	}
-  	
-	/** Advance is a lucene terminology to search for the next match.
-	 * */
-    protected boolean advance() throws IOException {	    	
-		// The complexity is linear for searching in a document. 
-		// It's better if we can skip to >= position in a document.
-	  	while (hasMoreSpans && ensureSameDoc(firstSpans,secondSpans)){
-	  		int matchCase = findMatch();
-				if (matchCase == 0){
-					//log.trace("Match doc#: {}",matchDocNumber);
-					//log.trace("Match positions: {}-{}", matchStartPosition,matchEndPosition);
-					doCollectPayloads();
-					return true;
-				} 
-				else if (matchCase == 1) {
-					hasMoreSpans = secondSpans.next();			
-				}			
-				else{ 
-					hasMoreSpans = firstSpans.next();
-				}
-			}
-		return false;
-	}
-    
-    /** Specify the condition for a match 
-     * @return 0 iff match is found,
-     * 			-1 to advance the firstspan,		
-     * 			1 to advance the secondspan
+    public boolean next() throws IOException {
+        // Warning: this does not work for overlapping spans 
+        // e.g. get multiple second spans in a firstspan
+        hasMoreSpans &= firstSpans.next();
+        isStartEnumeration = false;
+        matchPayload.clear();
+        return advance();
+    }
+
+    /**
+     * Advances to the next match.
+     * 
+     * @return <code>true</code> if a match is found, <code>false</code>
+     *         otherwise.
+     * @throws IOException
+     */
+    protected boolean advance() throws IOException {
+        // The complexity is linear for searching in a document. 
+        // It's better if we can skip to >= position in a document.
+        while (hasMoreSpans && ensureSameDoc(firstSpans, secondSpans)) {
+            int matchCase = findMatch();
+            if (matchCase == 0) {
+                doCollectPayloads();
+                return true;
+            } else if (matchCase == 1) {
+                hasMoreSpans = secondSpans.next();
+            } else {
+                hasMoreSpans = firstSpans.next();
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Specifies the condition for a match.
+     * 
+     * @return 0 iff match is found, -1 to advance the firstspan, 1 to advance
+     *         the secondspan
      * */
-  	protected abstract int findMatch();
-    
-  	/** Collecting available payloads from the current first and second spans */
-  	private void doCollectPayloads() throws IOException {
-  		Collection<byte[]> payload;
-  		if (collectPayloads){
-  		    if (firstSpans.isPayloadAvailable()) {
-  		    	 payload = firstSpans.getPayload();
-  		    	matchPayload.addAll(payload);
-  		    }
-  		    if (secondSpans.isPayloadAvailable()) {
-  		    	payload = secondSpans.getPayload();
-  		    	matchPayload.addAll(payload);
-  		    }
-  		}
-  	}
-    
-  	@Override
-  	public boolean skipTo(int target) throws IOException {		
-  		if (hasMoreSpans && (firstSpans.doc() < target)){
-  			if (!firstSpans.skipTo(target)){
-  				hasMoreSpans = false;
-  				return false;
-  			}			
-  		} 		
-  		matchPayload.clear();
-  		return advance();
-  	}
-  	
-  	@Override
-  	public long cost() {
-  		return firstSpans.cost() + secondSpans.cost();
-  	}
+    protected abstract int findMatch();
+
+    /**
+     * Collects available payloads from the current first and second spans.
+     * 
+     * @throws IOException
+     */
+    private void doCollectPayloads() throws IOException {
+        Collection<byte[]> payload;
+        if (collectPayloads) {
+            if (firstSpans.isPayloadAvailable()) {
+                payload = firstSpans.getPayload();
+                matchPayload.addAll(payload);
+            }
+            if (secondSpans.isPayloadAvailable()) {
+                payload = secondSpans.getPayload();
+                matchPayload.addAll(payload);
+            }
+        }
+    }
+
+    @Override
+    public boolean skipTo(int target) throws IOException {
+        if (hasMoreSpans && (firstSpans.doc() < target)) {
+            if (!firstSpans.skipTo(target)) {
+                hasMoreSpans = false;
+                return false;
+            }
+        }
+        matchPayload.clear();
+        return advance();
+    }
+
+    @Override
+    public long cost() {
+        return firstSpans.cost() + secondSpans.cost();
+    }
 }
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/OrderedDistanceSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/OrderedDistanceSpans.java
index 52185e8..761fa95 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/OrderedDistanceSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/OrderedDistanceSpans.java
@@ -27,7 +27,7 @@
     protected int candidateListDocNum;
 
     /**
-     * Constructs an OrderedDistanceSpans based on the given SpanDistanceQuery.
+     * Constructs OrderedDistanceSpans based on the given SpanDistanceQuery.
      * 
      * @param query a SpanDistanceQuery
      * @param context
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/RelationBaseSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/RelationBaseSpans.java
index 914bf7f..a6b1635 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/RelationBaseSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/RelationBaseSpans.java
@@ -27,7 +27,7 @@
     protected int rightStart, rightEnd;
 
     /**
-     * Create a RelationBaseSpans based on the given SpanWithIdQuery.
+     * Constructs RelationBaseSpans based on the given SpanWithIdQuery.
      * 
      * @param spanWithIdQuery a SpanWithIdQuery, for instance a
      *        {@link SpanElementQuery} or {@link SpanRelationQuery}.
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/RelationPartSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/RelationPartSpans.java
index 98ccf18..04af3e5 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/RelationPartSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/RelationPartSpans.java
@@ -37,7 +37,7 @@
     private int window; // number of tokens as the window
 
     /**
-     * Creates a RelationPartSpans from the specified
+     * Constructs RelationPartSpans from the specified
      * {@link SpanRelationPartQuery}.
      * 
      * @param query a SpanRelationPartQuery
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/RelationSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/RelationSpans.java
index 05de6d5..abb8fda 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/RelationSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/RelationSpans.java
@@ -54,7 +54,7 @@
     private List<CandidateRelationSpan> candidateList;
 
     /**
-     * Creates a RelationSpans from the given {@link SpanRelationQuery}.
+     * Constructs RelationSpans from the given {@link SpanRelationQuery}.
      * 
      * @param relationSpanQuery a SpanRelationQuery
      * @param context
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/SegmentSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/SegmentSpans.java
index d4a0e58..432862f 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/SegmentSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/SegmentSpans.java
@@ -10,37 +10,46 @@
 
 import de.ids_mannheim.korap.query.SpanSegmentQuery;
 
-/**	SegmentSpans is an enumeration of Span matches, which ensures that two spans 
- * 	have exactly the same start and end positions. It also represents the span 
- * 	match object. This is not very neat, but that is the Lucene's design.
+/**
+ * SegmentSpans is an enumeration of Span matches in which that two child spans
+ * have exactly the same start and end positions.
  * 
- * 	@author margaretha 
+ * @author margaretha
  * */
-public class SegmentSpans extends NonPartialOverlappingSpans {	
-	
-    public SegmentSpans (SpanSegmentQuery spanSegmentQuery,
-  	      AtomicReaderContext context,
-  	      Bits acceptDocs,
-  	      Map<Term,TermContext> termContexts) throws IOException {
-    	super(spanSegmentQuery, context, acceptDocs, termContexts);    	
+public class SegmentSpans extends NonPartialOverlappingSpans {
+
+    /**
+     * Creates SegmentSpans from the given {@link SpanSegmentQuery}.
+     * 
+     * @param spanSegmentQuery a spanSegmentQuery.
+     * @param context
+     * @param acceptDocs
+     * @param termContexts
+     * @throws IOException
+     */
+    public SegmentSpans(SpanSegmentQuery spanSegmentQuery,
+            AtomicReaderContext context, Bits acceptDocs,
+            Map<Term, TermContext> termContexts) throws IOException {
+        super(spanSegmentQuery, context, acceptDocs, termContexts);
     }
 
-    /** Check weather the start and end positions of the current 
-     * 	firstspan and secondspan are identical. 
-  	 * */
+    /**
+     * Check weather the start and end positions of the current firstspan and
+     * secondspan are identical.
+     * 
+     * */
     @Override
-	protected int findMatch() {
-		if (firstSpans.start() == secondSpans.start() &&
-			firstSpans.end() == secondSpans.end() ){
-			matchDocNumber = firstSpans.doc();
-			matchStartPosition = firstSpans.start();
-			matchEndPosition = firstSpans.end();			
-			return 0;
-		}
-		else if (firstSpans.start() < secondSpans.start() || 
-				firstSpans.end() < secondSpans.end())
-			return -1;
-		
-		return 1;
-	}	
+    protected int findMatch() {
+        if (firstSpans.start() == secondSpans.start()
+                && firstSpans.end() == secondSpans.end()) {
+            matchDocNumber = firstSpans.doc();
+            matchStartPosition = firstSpans.start();
+            matchEndPosition = firstSpans.end();
+            return 0;
+        } else if (firstSpans.start() < secondSpans.start()
+                || firstSpans.end() < secondSpans.end())
+            return -1;
+
+        return 1;
+    }
 }
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/SpansWithAttribute.java b/src/main/java/de/ids_mannheim/korap/query/spans/SpansWithAttribute.java
index a9723e8..0362bfa 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/SpansWithAttribute.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/SpansWithAttribute.java
@@ -36,7 +36,7 @@
     protected Logger logger = LoggerFactory.getLogger(SpansWithAttribute.class);
 
     /**
-     * Creates a SpansWithAttribute from the given
+     * Constructs SpansWithAttribute from the given
      * {@link SpanWithAttributeQuery} and {@link SpansWithId}, such as
      * elementSpans and relationSpans.
      * 
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/SubSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/SubSpans.java
index 0d984cd..c691a46 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/SubSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/SubSpans.java
@@ -10,59 +10,89 @@
 
 import de.ids_mannheim.korap.query.SpanSubspanQuery;
 
-public class SubSpans extends SimpleSpans{
+/**
+ * Enumeration of SubSpans, which are parts of another Spans. The SubSpans are
+ * specified with a start offset relative to the original span and a length.
+ * 
+ * @author margaretha
+ * 
+ */
+public class SubSpans extends SimpleSpans {
 
-	private int startOffset, length;
-	
-	public SubSpans(SpanSubspanQuery subspanQuery,
-			AtomicReaderContext context, Bits acceptDocs,
-			Map<Term, TermContext> termContexts) throws IOException {
-		super(subspanQuery, context, acceptDocs, termContexts);
-		this.startOffset= subspanQuery.getStartOffset();
-		this.length = subspanQuery.getLength();
-		hasMoreSpans = firstSpans.next();
-	}
+    private int startOffset, length;
 
-	@Override
-	public boolean next() throws IOException {
-		isStartEnumeration=false;		
-		return advance();
-	}
+    /**
+     * Constructs SubSpans for the given {@link SpanSubspanQuery} specifiying
+     * the start offset and the length of the subspans.
+     * 
+     * @param subspanQuery a SpanSubspanQuery
+     * @param context
+     * @param acceptDocs
+     * @param termContexts
+     * @throws IOException
+     */
+    public SubSpans(SpanSubspanQuery subspanQuery, AtomicReaderContext context,
+            Bits acceptDocs, Map<Term, TermContext> termContexts)
+            throws IOException {
+        super(subspanQuery, context, acceptDocs, termContexts);
+        this.startOffset = subspanQuery.getStartOffset();
+        this.length = subspanQuery.getLength();
+        hasMoreSpans = firstSpans.next();
+    }
 
-	private boolean advance() throws IOException {
-		while (hasMoreSpans){
-			setMatch();
-			hasMoreSpans = firstSpans.next();
-			return true;
-		}
-		return false;
-	}
-	
-	public void setMatch() throws IOException {
-		if (this.startOffset < 0)
-			matchStartPosition = firstSpans.end() + startOffset;
-		else matchStartPosition = firstSpans.start() + startOffset;
-		
-		matchEndPosition = matchStartPosition + this.length;
-		matchPayload = firstSpans.getPayload();
-		matchDocNumber = firstSpans.doc();
-	}
-	
-	@Override
-	public boolean skipTo(int target) throws IOException {
-		if (hasMoreSpans && (firstSpans.doc() < target)){
-  			if (!firstSpans.skipTo(target)){
-  				hasMoreSpans = false;
-  				return false;
-  			}
-  		} 		
-  		matchPayload.clear();
-  		return advance();
-	}
+    @Override
+    public boolean next() throws IOException {
+        isStartEnumeration = false;
+        return advance();
+    }
 
-	@Override
-	public long cost() {		
-		return firstSpans.cost() + 1;
-	}
+    /**
+     * Advances the SubSpans to the next match.
+     * 
+     * @return <code>true</code> if a match is found, <code>false</code>
+     *         otherwise.
+     * @throws IOException
+     */
+    private boolean advance() throws IOException {
+        while (hasMoreSpans) {
+            setMatch();
+            hasMoreSpans = firstSpans.next();
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Sets the properties of the current match/subspan.
+     * 
+     * @throws IOException
+     */
+    public void setMatch() throws IOException {
+        if (this.startOffset < 0)
+            matchStartPosition = firstSpans.end() + startOffset;
+        else
+            matchStartPosition = firstSpans.start() + startOffset;
+
+        matchEndPosition = matchStartPosition + this.length;
+        matchPayload = firstSpans.getPayload();
+        matchDocNumber = firstSpans.doc();
+    }
+
+    @Override
+    public boolean skipTo(int target) throws IOException {
+        if (hasMoreSpans && (firstSpans.doc() < target)) {
+            if (!firstSpans.skipTo(target)) {
+                hasMoreSpans = false;
+                return false;
+            }
+        }
+        matchPayload.clear();
+        return advance();
+    }
+
+    @Override
+    public long cost() {
+        return firstSpans.cost() + 1;
+    }
 
 }
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/TokenDistanceSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/TokenDistanceSpans.java
index 150c61e..fcfab27 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/TokenDistanceSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/TokenDistanceSpans.java
@@ -22,7 +22,7 @@
 public class TokenDistanceSpans extends OrderedDistanceSpans {
 
     /**
-     * Constructs a TokenDistanceSpans from the given query.
+     * Constructs TokenDistanceSpans from the given query.
      * 
      * @param query a SpanDistanceQuery
      * @param context
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedDistanceSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedDistanceSpans.java
index 8f68c8d..0d29645 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedDistanceSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedDistanceSpans.java
@@ -33,8 +33,8 @@
     protected int currentDocNum;
 
     /**
-     * Constructs an UnorderedDistanceSpans for the given
-     * {@link SpanDistanceQuery}.
+     * Constructs UnorderedDistanceSpans for the given {@link SpanDistanceQuery}
+     * .
      * 
      * @param query a SpanDistanceQuery
      * @param context
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedElementDistanceSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedElementDistanceSpans.java
index 102b5c9..f0df28e 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedElementDistanceSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedElementDistanceSpans.java
@@ -34,7 +34,7 @@
     private List<CandidateSpan> elementList;
 
     /**
-     * Constructs an UnorderedElementDistanceSpans for the given
+     * Constructs UnorderedElementDistanceSpans for the given
      * {@link SpanDistanceQuery}.
      * 
      * @param query a SpanDistanceQuery
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedTokenDistanceSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedTokenDistanceSpans.java
index bc9f0e5..c5061d3 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedTokenDistanceSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/UnorderedTokenDistanceSpans.java
@@ -23,8 +23,7 @@
 public class UnorderedTokenDistanceSpans extends UnorderedDistanceSpans {
 
     /**
-     * Constructs an UnorderedTokenDistanceSpans for the given
-     * SpanDistanceQuery.
+     * Constructs UnorderedTokenDistanceSpans for the given SpanDistanceQuery.
      * 
      * @param query a SpanDistanceQuery
      * @param context