From 51b155c0a8759a52d6a06ef1efd4dc9b0dbb2985 Mon Sep 17 00:00:00 2001
From: Oliver Gierke <ogierke@pivotal.io>
Date: Sat, 21 Mar 2015 18:19:28 +0100
Subject: [PATCH] DATACMNS-654 - Polishing.

Removed obsolete line-breaks in repositories documentation. Replace TWR worth with less ambiguous try-with-resources. Slight rewording. A few more details and fixed use of monospace font in return type reference.

Original pull request: #119.
---
 src/main/asciidoc/repositories.adoc           | 16 +++++-------
 ...pository-query-return-types-reference.adoc | 26 +++++++++----------
 2 files changed, 19 insertions(+), 23 deletions(-)

diff --git a/src/main/asciidoc/repositories.adoc b/src/main/asciidoc/repositories.adoc
index 2c218ae8c..5e5ad6a88 100644
--- a/src/main/asciidoc/repositories.adoc
+++ b/src/main/asciidoc/repositories.adoc
@@ -1,5 +1,3 @@
-:spring-framework-docs: http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html
-
 [[repositories]]
 = Working with Spring Data Repositories
 
@@ -335,9 +333,7 @@ NOTE: Note that limiting the results in combination with dynamic sorting via a `
 [[repositories.query-streaming]]
 === Streaming query results
 
-The results of query methods can be processed incrementally by using a Java 8 `Stream<T>` as return type.
-Instead of simply wrapping the query results in a `Stream` data store specific methods are used to
-perform the streaming.
+The results of query methods can be processed incrementally by using a Java 8 `Stream<T>` as return type. Instead of simply wrapping the query results in a `Stream` data store specific methods are used to perform the streaming.
 
 .Stream the result of a query with Java 8 `Stream<T>`
 ====
@@ -352,18 +348,18 @@ Stream<User> readAllByFirstnameNotNull();
 Stream<User> streamAllPaged(Pageable pageable);
 ----
 ====
-NOTE: A `Stream` potentially wraps underlying data store specific resources and must therefore be closed after usage. The closing can be done manually via the `close()` method of `Stream` or by using a  Java 7 `TWR`-block.
+NOTE: A `Stream` potentially wraps underlying data store specific resources and must therefore be closed after usage. You can either manually close the `Stream` using the `close()` method or by using a Java 7 try-with-resources block.
 
-.Working with a `Stream<T>` result in a TWR block
+.Working with a `Stream<T>` result in a try-with-resources block
 ====
 [source, java]
 ----
-try (Stream<User> stream = repository.findAllByCustomQueryAndStream()){
-  stream.forEach(/* process user */);
+try (Stream<User> stream = repository.findAllByCustomQueryAndStream()) {
+  stream.forEach(…);
 }
 ----
 ====
-NOTE: Not all data store specific repository implementations support `Stream<T>` as a return type.
+NOTE: Not all Spring Data modules currently support `Stream<T>` as a return type.
 
 [[repositories.create-instances]]
 == Creating repository instances
diff --git a/src/main/asciidoc/repository-query-return-types-reference.adoc b/src/main/asciidoc/repository-query-return-types-reference.adoc
index ad8ab81cf..780999ba2 100644
--- a/src/main/asciidoc/repository-query-return-types-reference.adoc
+++ b/src/main/asciidoc/repository-query-return-types-reference.adoc
@@ -1,24 +1,24 @@
-[[repository-query-return-types]]
 [appendix]
+[[repository-query-return-types]]
 = Repository query return types
 
 == Supported query return types
-The following table lists the return types generally supported by Spring Data repositories. However, consult the store-specific documentation for the exact list of supported return-types, because some listed here might not be supported in a particular store.
+The following table lists the return types generally supported by Spring Data repositories. However, consult the store-specific documentation for the exact list of supported return types, because some listed here might not be supported in a particular store.
 
 .Query return types
 [options="header", cols="1,3"]
 |===============
 |Return type|Description
-|`void`|`Denotes no return value`
-|`Primitives`|`Java primitives`
-|`Wrapper types`|`Java wrapper types`
-|`T`|`An entity or single attribute type T`
-|`Iterator<T>`|`Iterator`
-|`Collection<T>`|`Collection`
-|`List<T>`|`List`
-|`Optional<T>`|`Java 8 or Guava Optional`
-|`Stream<T>`|`Java 8 Stream`
-|`Slice`|`A sized chunk of data with information whether there is more data available.`
-|`Page<T>`|`A Slice with additional information, e.g. total # of results.`
+|`void`|Denotes no return value.
+|Primitives|Java primitives.
+|Wrapper types|Java wrapper types.
+|`T`|An unique entity. Expects the query method to return one result at most. In case no result is found `null` is returned. More than one result will trigger an `IncorrectResultSizeDataAccessException`.
+|`Iterator<T>`|An `Iterator`.
+|`Collection<T>`|A`Collection`.
+|`List<T>`|A `List`.
+|`Optional<T>`|A Java 8 or Guava `Optional`. Expects the query method to return one result at most. In case no result is found `Optional.empty()`/`Optional.absent()` is returned. More than one result will trigger an `IncorrectResultSizeDataAccessException`.
+|`Stream<T>`|A Java 8 `Stream`.
+|`Slice`|A sized chunk of data with information whether there is more data available. Requires a `Pageable` method parameter.
+|`Page<T>`|A Slice with additional information, e.g. the total number of results. Requires a `Pageable` method parameter.
 |===============