diff --git a/src/java/org/apache/lucene/search/payloads/BoostingFunctionTermQuery.java b/src/java/org/apache/lucene/search/payloads/BoostingFunctionTermQuery.java
index 38da05d5213..b253c440fa7 100644
--- a/src/java/org/apache/lucene/search/payloads/BoostingFunctionTermQuery.java
+++ b/src/java/org/apache/lucene/search/payloads/BoostingFunctionTermQuery.java
@@ -32,11 +32,16 @@ import org.apache.lucene.search.spans.SpanScorer;
 
 import java.io.IOException;
 
-
 /**
- * The score returned is based on the maximum payload score seen for the Term on the document, as opposed
- * to the average as implemented by {@link org.apache.lucene.search.payloads.BoostingTermQuery}.
- *
+ * This class is very similar to {@link org.apache.lucene.search.spans.SpanTermQuery} 
+ * except that it factors in the value of the payload located at each of the positions
+ *  where the {@link org.apache.lucene.index.Term} occurs.
+ * <p>
+ * In order to take advantage of this, you must override
+ * {@link org.apache.lucene.search.Similarity#scorePayload(String, byte[],int,int)}
+ * which returns 1 by default.
+ * <p>
+ * Payload scores are aggregated using a pluggable {@link PayloadFunction}.
  **/
 public class BoostingFunctionTermQuery extends SpanTermQuery  implements PayloadQuery{
   protected PayloadFunction function;
diff --git a/src/java/org/apache/lucene/search/payloads/BoostingNearQuery.java b/src/java/org/apache/lucene/search/payloads/BoostingNearQuery.java
index 53b397090b0..cac31e8b9d5 100644
--- a/src/java/org/apache/lucene/search/payloads/BoostingNearQuery.java
+++ b/src/java/org/apache/lucene/search/payloads/BoostingNearQuery.java
@@ -35,14 +35,14 @@ import java.util.Collection;
 import java.util.Iterator;
 
 /**
- * The BoostingNearQuery is very similar to the {@link org.apache.lucene.search.spans.SpanNearQuery} except
+ * This class is very similar to {@link org.apache.lucene.search.spans.SpanNearQuery} except
  * that it factors in the value of the payloads located at each of the positions where the
  * {@link org.apache.lucene.search.spans.TermSpans} occurs.
  * <p/>
  * In order to take advantage of this, you must override {@link org.apache.lucene.search.Similarity#scorePayload(String, byte[],int,int)}
  * which returns 1 by default.
  * <p/>
- * Payload scores are averaged across term occurrences in the document.
+ * Payload scores are aggregated using a pluggable {@link PayloadFunction}.
  *
  * @see org.apache.lucene.search.Similarity#scorePayload(String, byte[], int, int)
  */