From 5ee04edaf9117884a241031ff4c52fde995ac0b7 Mon Sep 17 00:00:00 2001
From: Jens Schauder <jschauder@pivotal.io>
Date: Thu, 6 Jun 2019 14:43:05 +0200
Subject: [PATCH] DATAJPA-707 - Documentation.

Reworked the stored procedure documentation since it was rather confusing.
Added a paragraph about stored procedures.

Original pull request: #297.
---
 src/main/asciidoc/jpa.adoc | 43 +++++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 15 deletions(-)

diff --git a/src/main/asciidoc/jpa.adoc b/src/main/asciidoc/jpa.adoc
index 65f0029a8..95bd676f3 100644
--- a/src/main/asciidoc/jpa.adoc
+++ b/src/main/asciidoc/jpa.adoc
@@ -643,9 +643,10 @@ include::{spring-data-commons-docs}/repository-projections.adoc[leveloffset=+2]
 
 [[jpa.stored-procedures]]
 == Stored Procedures
-The JPA 2.1 specification introduced support for calling stored procedures by using the JPA criteria query API. We Introduced the `@Procedure` annotation for declaring stored procedure metadata on a repository method.
+The JPA 2.1 specification introduced support for calling stored procedures by using the JPA criteria query API.
+We Introduced the `@Procedure` annotation for declaring stored procedure metadata on a repository method.
 
-The examples to follow use the following procedure:
+The examples to follow use the following stored procedure:
 
 .The definition of the `plus1inout` procedure in HSQL DB.
 ====
@@ -677,7 +678,15 @@ public class User {}
 ----
 ====
 
-You can reference stored procedures from a repository method in multiple ways. The stored procedure to be called can either be defined directly by using the `value` or `procedureName` attribute of the `@Procedure` annotation or indirectly by using the `name` attribute. If no name is configured, the name of the repository method is used as a fallback.
+Note that `@NamedStoredProcedureQuery` has two different names for the stored procedure.
+`name` is the name JPA uses. `procedureName` is the name the stored procedure has in the database.
+
+You can reference stored procedures from a repository method in multiple ways.
+The stored procedure to be called can either be defined directly by using the `value` or `procedureName` attribute of the `@Procedure` annotation.
+This referes directly to the stored procedure in the database and ignores any configuration via `@NamedStoredProcedureQuery`.
+
+Alternatively you may specify the `@NamedStoredProcedureQuery.name` attribute as the `@Procedure.name` attribute.
+If neither `value`, `procedureName` nor `name` is configured, the name of the repository method is used as the `name` attribute.
 
 The following example shows how to reference an explicitly mapped procedure:
 
@@ -691,18 +700,29 @@ Integer explicitlyNamedPlus1inout(Integer arg);
 ----
 ====
 
-The following example shows how to reference an implicitly mapped procedure by using a `procedureName` alias:
+The following example is equivalent to the previous one but uses the `procedureName` alias:
 
 .Referencing implicitly mapped procedure with name "plus1inout" in database via `procedureName` alias.
 ====
 [source, java]
 ----
 @Procedure(procedureName = "plus1inout")
-Integer plus1inout(Integer arg);
+Integer callPlus1InOut(Integer arg);
 ----
 ====
 
-The following example shows how to reference an explicitly mapped named procedure in `EntityManager`:
+The following is again equivalent to the previous two but using the method name instead of an explicite annotation attribute.
+
+.Referencing implicitly mapped named stored procedure "User.plus1" in `EntityManager` by using the method name.
+====
+[source, java]
+----
+@Procedure
+Integer plus1inout(@Param("arg") Integer arg);
+----
+====
+
+The following example shows how to reference a stored procedure by referencing the `@NamedStoredProcedureQuery.name` attribute.
 
 .Referencing explicitly mapped named stored procedure "User.plus1IO" in `EntityManager`.
 ====
@@ -713,16 +733,9 @@ Integer entityAnnotatedCustomNamedProcedurePlus1IO(@Param("arg") Integer arg);
 ----
 ====
 
-The following example shows how to reference an implicitly named stored procedure in `EntityManager` by using the method name:
+If the stored procedure getting called has a single out parameter that parameter may be returned as the return value of the method.
+If there are multiple out parameters specified in a `@NamedStoredProcedureQuery` annotation those can be returned as a `Map` with the key being the parameter name given in the `@NamedStoredProcedureQuery` annotation.
 
-.Referencing implicitly mapped named stored procedure "User.plus1" in `EntityManager` by using the method name.
-====
-[source, java]
-----
-@Procedure
-Integer plus1(@Param("arg") Integer arg);
-----
-====
 
 [[specifications]]
 == Specifications