From 5fdca06dd1c4a440fccc0a3c47e478d8d84137c7 Mon Sep 17 00:00:00 2001
From: Lukas Eder <lukas.eder@gmail.com>
Date: Tue, 8 Oct 2013 13:56:49 +0200
Subject: [PATCH] Added remarks about VisitListener being experimental

---
 jOOQ/src/main/java/org/jooq/Clause.java       |  7 +-
 .../src/main/java/org/jooq/VisitListener.java | 73 ++++++++++---------
 2 files changed, 43 insertions(+), 37 deletions(-)

diff --git a/jOOQ/src/main/java/org/jooq/Clause.java b/jOOQ/src/main/java/org/jooq/Clause.java
index c92968992c..bdfa7c58bb 100644
--- a/jOOQ/src/main/java/org/jooq/Clause.java
+++ b/jOOQ/src/main/java/org/jooq/Clause.java
@@ -40,8 +40,11 @@
  */
 package org.jooq;
 
-/**
- * A listing of clauses that emit events {@link VisitListener}.
+/**
+ * A listing of clauses that emit events {@link VisitListener}.
+ * <p>
+ * <h3>Disclaimer</h3> This SPI is still <strong>experimental</strong>! Some SPI
+ * elements and/or behavioural elements may change in future minor releases.
  */
 public enum Clause {
 
diff --git a/jOOQ/src/main/java/org/jooq/VisitListener.java b/jOOQ/src/main/java/org/jooq/VisitListener.java
index 3584f54e6e..6033978377 100644
--- a/jOOQ/src/main/java/org/jooq/VisitListener.java
+++ b/jOOQ/src/main/java/org/jooq/VisitListener.java
@@ -40,33 +40,33 @@
  */
 package org.jooq;
 
-import java.sql.PreparedStatement;
-import java.util.EventListener;
+import java.sql.PreparedStatement;
+import java.util.EventListener;
 
-/**
- * A listener for {@link QueryPart} traversal events.
- * <p>
- * Users may want to centrally inject custom behaviour when rendering their
- * {@link QueryPart} objects or when binding values to {@link PreparedStatement}
- * s. This service provider allows to hook in callback method implementations
- * before or after these events:
- * <ul>
- * <li>The visit of a {@link Clause}</li>
- * <li>The visit of a {@link QueryPart}</li>
- * </ul>
- * <p>
- * The following rules apply to visiting clauses and query parts:
- * <ul>
- * <li>Clauses may "surround" a query part. See an example below.</li>
- * <li>Not every query part is "surrounded" by a clause</li>
- * </ul>
- * <p>
- * An example is given here:
- * <code><pre>SELECT 1 FROM [A CROSS JOIN B]</pre></code>
- * <p>
- * The above example will create the following set of events:
- *
- * <pre>
+/**
+ * A listener for {@link QueryPart} traversal events.
+ * <p>
+ * Users may want to centrally inject custom behaviour when rendering their
+ * {@link QueryPart} objects or when binding values to {@link PreparedStatement}
+ * s. This service provider allows to hook in callback method implementations
+ * before or after these events:
+ * <ul>
+ * <li>The visit of a {@link Clause}</li>
+ * <li>The visit of a {@link QueryPart}</li>
+ * </ul>
+ * <p>
+ * The following rules apply to visiting clauses and query parts:
+ * <ul>
+ * <li>Clauses may "surround" a query part. See an example below.</li>
+ * <li>Not every query part is "surrounded" by a clause</li>
+ * </ul>
+ * <p>
+ * An example is given here:
+ * <code><pre>SELECT 1 FROM [A CROSS JOIN B]</pre></code>
+ * <p>
+ * The above example will create the following set of events:
+ *
+ * <pre>
  * {@link Clause#SELECT}
  * +-{@link Clause#SELECT_SELECT}
  * | +-{@link Clause#FIELD}
@@ -77,15 +77,18 @@ import java.util.EventListener;
  *     | +-table("A")
  *     +-{@link Clause#TABLE_JOIN_CROSS}
  *       +-{@link Clause#TABLE}
- *         +-table("B")
- * </pre>
- * <p>
- * Whatever is not a {@link Clause} in the above example is a {@link QueryPart}.
- * <p>
- * Note: [#2694] [#2695] As of jOOQ 3.2, {@link VisitListener} receive events
- * only in the context of a {@link RenderContext}, not of a {@link BindContext}.
- *
- * @author Lukas Eder
+ *         +-table("B")
+ * </pre>
+ * <p>
+ * Whatever is not a {@link Clause} in the above example is a {@link QueryPart}.
+ * <p>
+ * Note: [#2694] [#2695] As of jOOQ 3.2, {@link VisitListener} receive events
+ * only in the context of a {@link RenderContext}, not of a {@link BindContext}.
+ * <p>
+ * <h3>Disclaimer</h3> This SPI is still <strong>experimental</strong>! Some SPI
+ * elements and/or behavioural elements may change in future minor releases.
+ *
+ * @author Lukas Eder
  */
 public interface VisitListener extends EventListener {