From 7dd9bf9b52a750432f163d93b658580e5b8e3a97 Mon Sep 17 00:00:00 2001
From: Gunnar Morling <gunnar.morling@googlemail.com>
Date: Mon, 3 Jun 2013 17:28:54 +0200
Subject: [PATCH] HSEARCH-1345 Adding JavaDoc for QueryBuilder and
 QueryContextBuilder#forEntity()

---
 .../org/hibernate/search/query/dsl/QueryBuilder.java  |  6 ++++++
 .../search/query/dsl/QueryContextBuilder.java         | 11 +++++++++++
 2 files changed, 17 insertions(+)

diff --git a/engine/src/main/java/org/hibernate/search/query/dsl/QueryBuilder.java b/engine/src/main/java/org/hibernate/search/query/dsl/QueryBuilder.java
index 21c7d7196cb..43bdaf08849 100644
--- a/engine/src/main/java/org/hibernate/search/query/dsl/QueryBuilder.java
+++ b/engine/src/main/java/org/hibernate/search/query/dsl/QueryBuilder.java
@@ -25,6 +25,12 @@
 package org.hibernate.search.query.dsl;
 
 /**
+ * Builds up Lucene queries for a given entity type following the fluent API pattern. The resulting {@link Query} can
+ * be obtained from the final {@link Termination} object of the invocation chain.
+ * </p>
+ * If required, the resulting {@code Query} instance can be modified or combined with other queries, be them created
+ * via this fluent API or using native Lucene APIs.
+ *
  * @author Emmanuel Bernard
  */
 public interface QueryBuilder {
diff --git a/engine/src/main/java/org/hibernate/search/query/dsl/QueryContextBuilder.java b/engine/src/main/java/org/hibernate/search/query/dsl/QueryContextBuilder.java
index d8fd24749b0..b1c0aad0ba7 100644
--- a/engine/src/main/java/org/hibernate/search/query/dsl/QueryContextBuilder.java
+++ b/engine/src/main/java/org/hibernate/search/query/dsl/QueryContextBuilder.java
@@ -43,5 +43,16 @@
  */
 public interface QueryContextBuilder {
 	//TODO make a forEntities
+
+	/**
+	 * Creates an entity context which can be used to obtain a {@link QueryBuilder}.
+	 * </p>
+	 * Note that the passed entity type is used to verify field names, transparently apply analyzers and field bridges
+	 * etc. The query result list, however, is not automatically restricted to the given type. Instead a type filter
+	 * must be applied when creating the full text query in order to restrict the query result to certain entity types.
+	 *
+	 * @param entityType entity type used for meta data retrieval during query creation
+	 * @return an entity context
+	 */
 	EntityContext forEntity(Class<?> entityType);
 }