From 5beeaff9af75f89a0c1814db2f94a2392b606f46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Simon=20Basl=C3=A9?= <simon.basle@gmail.com>
Date: Thu, 15 Oct 2015 17:28:37 +0200
Subject: [PATCH] DATACOUCH-170 - Fix N1QL annotation and inline querying in
 docs

In some places in the doc (javadoc, README, asciidoc), the annotation was still referred to as N1QL instead of Query...

Improved doc on inline statement for N1QL queries allowing the use of positional `$1` placeholders.
---
 README.md                                                  | 7 +++++--
 src/main/asciidoc/migrating.adoc                           | 4 ++--
 src/main/asciidoc/repository.adoc                          | 2 +-
 .../couchbase/repository/query/StringN1qlBasedQuery.java   | 4 ++++
 4 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 783ba3ed..2aa06191 100644
--- a/README.md
+++ b/README.md
@@ -153,7 +153,7 @@ public interface UserRepository extends CrudRepository<UserInfo, String> {
   /**
    * Advanced querying with N1QL derivation
    */
-  @View
+  @Query
   List<UserInfo> findByLastnameEqualsIgnoreCaseAndFirstnameStartsWithAndIsAdultTrue(String lastName, String fnamePrefix);
 }
 ```
@@ -168,8 +168,11 @@ You can alternatively write the statement yourself inside the `@Query` annotatio
 placeholder to make sure all necessary fields and metadata are selected by N1QL:
 
 ```java
-@Query("$SELECT_ENTITY$ WHERE firstname LIKE "%ck%"
+@Query("$SELECT_ENTITY$ WHERE firstname LIKE "%ck%")
 List<UserInfo> findPatrickAndJackAmongOthers();
+
+@Query("$SELECT_ENTITY$ WHERE firstname LIKE $1")
+List<UserInfo> findUsersWithTheirFirstnameLike(String likePattern);
 ```
 
 ## Using The Repository
diff --git a/src/main/asciidoc/migrating.adoc b/src/main/asciidoc/migrating.adoc
index 39b2f8ab..851b40f3 100644
--- a/src/main/asciidoc/migrating.adoc
+++ b/src/main/asciidoc/migrating.adoc
@@ -21,8 +21,8 @@ The view-backed query method has evolved and support for N1QL has been introduce
 
  * Simple View query (to return all elements emitted by a view) - @View annotated without `viewName`
  * Intermediate View query by query derivation (to provide some criteria for the view) @View annotated with `viewName`
- * N1QL with explicit statements inline - @N1QL annotated with value
- * N1QL query derivation - @N1QL annotated without value / no annotation (default)
+ * N1QL with explicit statements inline - `@Query` annotated with value
+ * N1QL query derivation - `@Query` annotated without value / no annotation (default)
 
 View backed queries are associated with the `@View` annotation, while N1QL backed queries are associated with the `@Query` annotation.
 
diff --git a/src/main/asciidoc/repository.adoc b/src/main/asciidoc/repository.adoc
index 7c8182d2..f7ce885d 100644
--- a/src/main/asciidoc/repository.adoc
+++ b/src/main/asciidoc/repository.adoc
@@ -109,7 +109,7 @@ As of version `4.0`, Couchbase Server ships with a new query language called `N1
 
 Prerequisite is to have a N1QL-compatible cluster and to have created a PRIMARY INDEX on the bucket where the entities will be stored.
 
-WARNING: If it is detected at configuration time that the cluster doesn't support N1QL while there are @N1QL annotated methods or non-annotated methods in your repository interface, a `UnsupportedCouchbaseFeatureException` will be thrown.
+WARNING: If it is detected at configuration time that the cluster doesn't support N1QL while there are `@Query` annotated methods or non-annotated methods in your repository interface, a `UnsupportedCouchbaseFeatureException` will be thrown.
 
 Here is an example:
 
diff --git a/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java b/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java
index 3960e4c1..a9b4b3a6 100644
--- a/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java
+++ b/src/main/java/org/springframework/data/couchbase/repository/query/StringN1qlBasedQuery.java
@@ -26,6 +26,10 @@ import org.springframework.data.repository.query.RepositoryQuery;
 
 /**
  * A {@link RepositoryQuery} for Couchbase, based on N1QL and a String statement.
+ * <p/>
+ * The statement can contain positional placeholders (eg. <code>name = $1</code>) that will map to the
+ * method's parameters, in the same order.
+ * <p/>
  * The statement can contain placeholders for the {@link #PLACEHOLDER_BUCKET bucket namespace},
  * the {@link #PLACEHOLDER_ENTITY ID and CAS fields} necessary for entity reconstruction or
  * a shortcut that covers {@link #PLACEHOLDER_SELECT_FROM SELECT AND FROM clauses}.