From 48966b50d6b5bbdc7e47f7ce24ed2d3e2f6cebfd Mon Sep 17 00:00:00 2001
From: Thomas Darimont <tdarimont@pivotal.io>
Date: Mon, 6 Oct 2014 10:53:03 +0200
Subject: [PATCH] DATACMNS-577 - Improved JavaDoc on QueryDslPredicateExecutor.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clarified return values if predicates don't match or return multiple results (for the findOne(…) method). Copied summary to the @return tag.

Original pull request: #96.
---
 .../querydsl/QueryDslPredicateExecutor.java   | 28 +++++++++++--------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/src/main/java/org/springframework/data/querydsl/QueryDslPredicateExecutor.java b/src/main/java/org/springframework/data/querydsl/QueryDslPredicateExecutor.java
index 54dc33723..5160b79cf 100644
--- a/src/main/java/org/springframework/data/querydsl/QueryDslPredicateExecutor.java
+++ b/src/main/java/org/springframework/data/querydsl/QueryDslPredicateExecutor.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2011 the original author or authors.
+ * Copyright 2011-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,7 @@
  */
 package org.springframework.data.querydsl;
 
+import org.springframework.dao.IncorrectResultSizeDataAccessException;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 
@@ -25,40 +26,45 @@ import com.mysema.query.types.Predicate;
  * Interface to allow execution of QueryDsl {@link Predicate} instances.
  * 
  * @author Oliver Gierke
+ * @author Thomas Darimont
  */
 public interface QueryDslPredicateExecutor<T> {
 
 	/**
-	 * Returns a single entity matching the given {@link Predicate}.
+	 * Returns a single entity matching the given {@link Predicate} or {@literal null} if none was found.
 	 * 
-	 * @param spec
-	 * @return
+	 * @param predicate
+	 * @return a single entity matching the given {@link Predicate} or {@literal null} if none was found.
+	 * @throws IncorrectResultSizeDataAccessException if the predicate yields more than one result.
 	 */
 	T findOne(Predicate predicate);
 
 	/**
-	 * Returns all entities matching the given {@link Predicate}.
+	 * Returns all entities matching the given {@link Predicate}. In case no match could be found an empty
+	 * {@link Iterable} is returned.
 	 * 
-	 * @param spec
-	 * @return
+	 * @param predicate
+	 * @return all entities matching the given {@link Predicate}.
 	 */
 	Iterable<T> findAll(Predicate predicate);
 
 	/**
-	 * Returns all entities matching the given {@link Predicate} applying the given {@link OrderSpecifier}s.
+	 * Returns all entities matching the given {@link Predicate} applying the given {@link OrderSpecifier}s. In case no
+	 * match could be found an empty {@link Iterable} is returned.
 	 * 
 	 * @param predicate
 	 * @param orders
-	 * @return
+	 * @return all entities matching the given {@link Predicate} applying the given {@link OrderSpecifier}s.
 	 */
 	Iterable<T> findAll(Predicate predicate, OrderSpecifier<?>... orders);
 
 	/**
-	 * Returns a {@link Page} of entities matching the given {@link Predicate}.
+	 * Returns a {@link Page} of entities matching the given {@link Predicate}. In case no match could be found, an empty
+	 * {@link Page} is returned.
 	 * 
 	 * @param predicate
 	 * @param pageable
-	 * @return
+	 * @return a {@link Page} of entities matching the given {@link Predicate}.
 	 */
 	Page<T> findAll(Predicate predicate, Pageable pageable);