From 7a22d697cfaca77e6f4f49b99da27bc7440e66f7 Mon Sep 17 00:00:00 2001
From: Mark Paluch <mpaluch@pivotal.io>
Date: Mon, 27 May 2019 10:56:43 +0200
Subject: [PATCH] DATAMONGO-2067 - Polishing.

Tweak Javadoc and reference docs. Use pre/class=code instead of nested code tag.

Original pull request: #756.
---
 .../mongodb/core/index/CompoundIndex.java     | 40 +++++++------------
 .../mongodb/core/index/CompoundIndexes.java   |  4 ++
 src/main/asciidoc/reference/mapping.adoc      | 10 ++---
 3 files changed, 22 insertions(+), 32 deletions(-)

diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java
index be7c1f8c7..c28549dec 100644
--- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java
+++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndex.java
@@ -25,23 +25,20 @@ import java.lang.annotation.Target;
 /**
  * Mark a class to use compound indexes.
  * <p />
- * Some situations may require to have more than one {@link CompoundIndex}. For those scenarios {@link CompoundIndexes}
- * functions as container annotation for multiple {@link CompoundIndex} annotations via the
- * {@link CompoundIndexes#value()} or by repeating the {@link CompoundIndex} on the class itself.
- * 
- * <pre>
- * <code>
- * 
+ * <p>
+ * <b>NOTE: This annotation is repeatable according to Java 8 conventions using {@link CompoundIndexes#value()} as
+ * container.</b>
+ *
+ * <pre class="code">
  * &#64;Document
  * &#64;CompoundIndex(def = "{'firstname': 1, 'lastname': 1}")
  * &#64;CompoundIndex(def = "{'address.city': 1, 'address.street': 1}")
  * class Person {
- *   String firstname;
- *   String lastname;
+ * 	String firstname;
+ * 	String lastname;
  *
- *   Address address;
+ * 	Address address;
  * }
- * </code>
  * </pre>
  *
  * @author Jon Brisbin
@@ -63,9 +60,7 @@ public @interface CompoundIndex {
 	 * <br />
 	 * If left empty on nested document, the whole document will be indexed.
 	 *
-	 * <pre>
-	 * <code>
-	 *
+	 * <pre class="code">
 	 * &#64;Document
 	 * &#64;CompoundIndex(def = "{'h1': 1, 'h2': 1}")
 	 * class JsonStringIndexDefinition {
@@ -77,7 +72,6 @@ public @interface CompoundIndex {
 	 * class ExpressionIndexDefinition {
 	 *   String h1, h2;
 	 * }
-	 * </code>
 	 * </pre>
 	 *
 	 * @return
@@ -127,35 +121,31 @@ public @interface CompoundIndex {
 	 * <br />
 	 * The structure below
 	 *
-	 * <pre>
-	 * <code>
+	 * <pre class="code">
 	 * &#64;Document
 	 * class Root {
-	 *   Hybrid hybrid;
-	 *   Nested nested;
+	 * 	Hybrid hybrid;
+	 * 	Nested nested;
 	 * }
 	 *
 	 * &#64;Document
 	 * &#64;CompoundIndex(name = "compound_index", def = "{'h1': 1, 'h2': 1}")
 	 * class Hybrid {
-	 *   String h1, h2;
+	 * 	String h1, h2;
 	 * }
 	 *
 	 * &#64;CompoundIndex(name = "compound_index", def = "{'n1': 1, 'n2': 1}")
 	 * class Nested {
-	 *   String n1, n2;
+	 * 	String n1, n2;
 	 * }
-	 * </code>
 	 * </pre>
 	 *
 	 * resolves in the following index structures
 	 *
-	 * <pre>
-	 * <code>
+	 * <pre class="code">
 	 * db.root.createIndex( { hybrid.h1: 1, hybrid.h2: 1 } , { name: "hybrid.compound_index" } )
 	 * db.root.createIndex( { nested.n1: 1, nested.n2: 1 } , { name: "nested.compound_index" } )
 	 * db.hybrid.createIndex( { h1: 1, h2: 1 } , { name: "compound_index" } )
-	 * </code>
 	 * </pre>
 	 *
 	 * @return
diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndexes.java b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndexes.java
index 6494a7a73..1d57079cb 100644
--- a/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndexes.java
+++ b/spring-data-mongodb/src/main/java/org/springframework/data/mongodb/core/index/CompoundIndexes.java
@@ -23,6 +23,10 @@ import java.lang.annotation.Target;
 
 /**
  * Container annotation that allows to collect multiple {@link CompoundIndex} annotations.
+ * <p>
+ * Can be used natively, declaring several nested {@link CompoundIndex} annotations. Can also be used in conjunction
+ * with Java 8's support for <em>repeatable annotations</em>, where {@link CompoundIndex} can simply be declared several
+ * times on the same {@linkplain ElementType#TYPE type}, implicitly generating this container annotation.
  *
  * @author Jon Brisbin
  * @author Christoph Strobl
diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc
index db2fee0ef..bbb790b50 100644
--- a/src/main/asciidoc/reference/mapping.adoc
+++ b/src/main/asciidoc/reference/mapping.adoc
@@ -428,9 +428,7 @@ Here is an example of a more complex mapping.
 [source,java]
 ----
 @Document
-@CompoundIndexes({
-    @CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")
-})
+@CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")
 public class Person<T extends Address> {
 
   @Id
@@ -570,9 +568,7 @@ Here's an example that creates a compound index of `lastName` in ascending order
 package com.mycompany.domain;
 
 @Document
-@CompoundIndexes({
-    @CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")
-})
+@CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")
 public class Person {
 
   @Id
@@ -587,7 +583,7 @@ public class Person {
 
 [TIP]
 ====
-`@CompoundIndex` is a repeatable annotation using `@CompoundIndexes` as the container.
+`@CompoundIndex` is repeatable using `@CompoundIndexes` as its container.
 
 [source,java]
 ----