From 62351f9e0ad5a5a16266aab5408475a077966d60 Mon Sep 17 00:00:00 2001
From: Dheeraj Mishra <dmishra@aerospike.com>
Date: Sat, 14 Feb 2026 23:20:46 +0530
Subject: [PATCH] CLIENT-4159: enriched doc

a
---
 .../src/com/aerospike/client/AbortStatus.java |   26 +-
 .../com/aerospike/client/AerospikeClient.java | 2154 +++++++++++------
 .../aerospike/client/AerospikeException.java  |  144 +-
 .../src/com/aerospike/client/BatchDelete.java |   20 +-
 .../src/com/aerospike/client/BatchRead.java   |   23 +-
 .../src/com/aerospike/client/BatchRecord.java |   24 +-
 client/src/com/aerospike/client/BatchUDF.java |   20 +-
 .../src/com/aerospike/client/BatchWrite.java  |   25 +-
 client/src/com/aerospike/client/Bin.java      |   32 +-
 .../src/com/aerospike/client/CommitError.java |   25 +-
 .../com/aerospike/client/CommitStatus.java    |   23 +-
 client/src/com/aerospike/client/Host.java     |   25 +-
 .../aerospike/client/IAerospikeClient.java    |    2 +
 client/src/com/aerospike/client/Info.java     |   32 +-
 client/src/com/aerospike/client/Key.java      |   42 +-
 client/src/com/aerospike/client/Language.java |   22 +-
 .../src/com/aerospike/client/Operation.java   |   20 +-
 client/src/com/aerospike/client/Record.java   |   33 +-
 .../src/com/aerospike/client/ResultCode.java  |   21 +-
 .../com/aerospike/client/ScanCallback.java    |   39 +-
 client/src/com/aerospike/client/Txn.java      |   28 +-
 client/src/com/aerospike/client/Value.java    |  179 +-
 .../com/aerospike/client/admin/Privilege.java |   38 +-
 .../aerospike/client/admin/PrivilegeCode.java |   30 +-
 .../src/com/aerospike/client/admin/Role.java  |   96 +-
 .../src/com/aerospike/client/admin/User.java  |   56 +-
 .../client/async/AsyncIndexTask.java          |   35 +-
 .../com/aerospike/client/async/EventLoop.java |   84 +-
 .../client/async/EventLoopStats.java          |   26 +-
 .../aerospike/client/async/EventLoopType.java |   26 +-
 .../aerospike/client/async/EventLoops.java    |   37 +-
 .../aerospike/client/async/EventPolicy.java   |   13 +-
 .../client/async/NettyEventLoops.java         |   34 +-
 .../client/async/NettyTlsContext.java         |   25 +-
 .../aerospike/client/async/NioEventLoops.java |   45 +-
 client/src/com/aerospike/client/cdt/CTX.java  |   28 +-
 .../aerospike/client/cdt/CdtOperation.java    |   29 +-
 .../aerospike/client/cdt/ListOperation.java   |   70 +-
 .../com/aerospike/client/cdt/ListOrder.java   |    7 +-
 .../com/aerospike/client/cdt/ListPolicy.java  |   20 +-
 .../aerospike/client/cdt/ListReturnType.java  |   12 +-
 .../aerospike/client/cdt/ListWriteFlags.java  |   10 +-
 .../aerospike/client/cdt/MapOperation.java    |   89 +-
 .../com/aerospike/client/cdt/MapOrder.java    |    7 +-
 .../com/aerospike/client/cdt/MapPolicy.java   |   21 +-
 .../aerospike/client/cdt/MapReturnType.java   |   12 +-
 .../aerospike/client/cdt/MapWriteFlags.java   |   10 +-
 .../configuration/ConfigurationProvider.java  |   33 +
 .../src/com/aerospike/client/exp/BitExp.java  |   26 +-
 .../src/com/aerospike/client/exp/CdtExp.java  |   20 +-
 client/src/com/aerospike/client/exp/Exp.java  |   41 +-
 .../aerospike/client/exp/ExpOperation.java    |   26 +-
 .../aerospike/client/exp/ExpReadFlags.java    |   19 +-
 .../aerospike/client/exp/ExpWriteFlags.java   |   10 +-
 .../com/aerospike/client/exp/Expression.java  |   18 +-
 .../src/com/aerospike/client/exp/HLLExp.java  |   37 +-
 .../src/com/aerospike/client/exp/ListExp.java |   76 +-
 .../com/aerospike/client/exp/LoopVarPart.java |   15 +-
 .../src/com/aerospike/client/exp/MapExp.java  |  108 +-
 .../client/listener/AbortListener.java        |   22 +-
 .../client/listener/BatchListListener.java    |   29 +-
 .../listener/BatchOperateListListener.java    |   29 +-
 .../listener/BatchRecordArrayListener.java    |   36 +-
 .../listener/BatchRecordSequenceListener.java |   36 +-
 .../listener/BatchSequenceListener.java       |   35 +-
 .../client/listener/ClusterStatsListener.java |   25 +-
 .../client/listener/CommitListener.java       |   26 +-
 .../client/listener/DeleteListener.java       |   28 +-
 .../client/listener/ExecuteListener.java      |   28 +-
 .../client/listener/ExistsArrayListener.java  |   34 +-
 .../client/listener/ExistsListener.java       |   29 +-
 .../listener/ExistsSequenceListener.java      |   36 +-
 .../client/listener/IndexListener.java        |   31 +-
 .../client/listener/InfoListener.java         |   29 +-
 .../client/listener/RecordArrayListener.java  |   34 +-
 .../client/listener/RecordListener.java       |   31 +-
 .../listener/RecordSequenceListener.java      |   54 +-
 .../client/listener/TaskStatusListener.java   |   24 +-
 .../client/listener/WriteListener.java        |   23 +-
 .../client/operation/BitOperation.java        |   24 +-
 .../client/operation/BitOverflowAction.java   |    6 +-
 .../aerospike/client/operation/BitPolicy.java |   20 +-
 .../client/operation/BitResizeFlags.java      |    6 +-
 .../client/operation/BitWriteFlags.java       |   12 +-
 .../client/operation/HLLOperation.java        |   21 +-
 .../aerospike/client/operation/HLLPolicy.java |   21 +-
 .../client/operation/HLLWriteFlags.java       |   13 +-
 .../aerospike/client/policy/AdminPolicy.java  |   16 +-
 .../com/aerospike/client/policy/AuthMode.java |    4 +-
 .../client/policy/BatchDeletePolicy.java      |   18 +-
 .../aerospike/client/policy/BatchPolicy.java  |   20 +-
 .../client/policy/BatchReadPolicy.java        |   19 +-
 .../client/policy/BatchUDFPolicy.java         |   18 +-
 .../client/policy/BatchWritePolicy.java       |   19 +-
 .../aerospike/client/policy/ClientPolicy.java |   29 +-
 .../aerospike/client/policy/CommitLevel.java  |    6 +-
 .../client/policy/GenerationPolicy.java       |    4 +-
 .../aerospike/client/policy/InfoPolicy.java   |   15 +-
 .../com/aerospike/client/policy/Policy.java   |   25 +-
 .../client/policy/QueryDuration.java          |    5 +-
 .../aerospike/client/policy/QueryPolicy.java  |   20 +-
 .../aerospike/client/policy/ReadModeAP.java   |    8 +-
 .../aerospike/client/policy/ReadModeSC.java   |    7 +-
 .../client/policy/RecordExistsAction.java     |    5 +-
 .../com/aerospike/client/policy/Replica.java  |    4 +-
 .../aerospike/client/policy/ScanPolicy.java   |   23 +-
 .../aerospike/client/policy/TCPKeepAlive.java |   10 +
 .../aerospike/client/policy/TlsPolicy.java    |   23 +-
 .../client/policy/TxnRollPolicy.java          |   20 +-
 .../client/policy/TxnVerifyPolicy.java        |   19 +-
 .../aerospike/client/policy/WritePolicy.java  |   21 +-
 .../com/aerospike/client/query/Filter.java    |   23 +-
 .../client/query/IndexCollectionType.java     |    8 +-
 .../com/aerospike/client/query/IndexType.java |    8 +-
 .../com/aerospike/client/query/KeyRecord.java |   20 +-
 .../client/query/PartitionFilter.java         |   16 +
 .../aerospike/client/query/QueryListener.java |   38 +-
 .../com/aerospike/client/query/RecordSet.java |   42 +-
 .../com/aerospike/client/query/RegexFlag.java |   11 +-
 .../com/aerospike/client/query/ResultSet.java |   35 +-
 .../com/aerospike/client/query/Statement.java |   30 +-
 .../src/com/aerospike/client/task/Task.java   |   23 +-
 122 files changed, 4122 insertions(+), 1480 deletions(-)

diff --git a/client/src/com/aerospike/client/AbortStatus.java b/client/src/com/aerospike/client/AbortStatus.java
index 4aee26c36..64e3b7a9d 100644
--- a/client/src/com/aerospike/client/AbortStatus.java
+++ b/client/src/com/aerospike/client/AbortStatus.java
@@ -17,7 +17,30 @@
 package com.aerospike.client;
 
 /**
- * Transaction abort status code.
+ * Transaction abort result returned by {@link com.aerospike.client.AerospikeClient#abort}. OK and ALREADY_ABORTED indicate success; abandoned statuses mean the server will complete asynchronously.
+ *
+ * <p><b>Example:</b>
+ * <p>Abort a transaction and check the returned status.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Txn txn = new Txn();
+ *   try {
+ *     client.commit(txn);
+ *   } catch (AerospikeException.Commit e) {
+ *     AbortStatus status = client.abort(txn);
+ *     if (status != AbortStatus.OK && status != AbortStatus.ALREADY_ABORTED) {
+ *       System.err.println(status.str);
+ *     }
+ *   }
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see CommitStatus
+ * @see CommitError
+ * @see com.aerospike.client.AerospikeClient#abort
  */
 public enum AbortStatus {
 	OK("Abort succeeded"),
@@ -25,6 +48,7 @@ public enum AbortStatus {
 	ROLL_BACK_ABANDONED("Transaction client roll back abandoned. Server will eventually abort the transaction."),
 	CLOSE_ABANDONED("Transaction has been rolled back, but transaction client close was abandoned. Server will eventually close the transaction.");
 
+	/** Human-readable message for this status. */
 	public final String str;
 
 	AbortStatus(String str) {
diff --git a/client/src/com/aerospike/client/AerospikeClient.java b/client/src/com/aerospike/client/AerospikeClient.java
index 5b520c195..8675f8e01 100644
--- a/client/src/com/aerospike/client/AerospikeClient.java
+++ b/client/src/com/aerospike/client/AerospikeClient.java
@@ -139,16 +139,28 @@
 import com.aerospike.client.util.Version;
 
 /**
- * Instantiate an <code>AerospikeClient</code> object to access an Aerospike
- * database cluster and perform database operations.
+ * Main client to access an Aerospike cluster and perform database operations (get, put, query, batch, etc.).
  * <p>
- * This client is thread-safe. One client instance should be used per cluster.
- * Multiple threads should share this cluster instance.
- * <p>
- * Your application uses this class API to perform database operations such as
- * writing and reading records, and selecting sets of records. Write operations
- * include specialized functionality such as append/prepend and arithmetic
- * addition.
+ * Thread-safe; use one instance per cluster and share it across threads. Implements {@link IAerospikeClient}. Use {@link ClientPolicy} and {@link Host} (or seed strings) to construct.
+ *
+ * <p><b>Example:</b>
+ * <p>Create a client, put a record, and get it back.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Key key = new Key("test", "set1", "id1");
+ *   client.put(null, key, new Bin("name", "Alice"));
+ *   Record rec = client.get(null, key);
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see IAerospikeClient
+ * @see ClientPolicy
+ * @see Host
+ * @see Key
+ * @see Record
  */
 public class AerospikeClient implements IAerospikeClient, Closeable {
 	//-------------------------------------------------------
@@ -768,10 +780,25 @@ public String getVersion() {
 	 * committed. Otherwise, the transaction is aborted.
 	 * <p>
 	 * Requires server version 8.0+
+	 * <p>
+	 * <p>Commit a transaction after put; check returned status.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("ns", "set", "txnkey");
+	 * Txn txn = new Txn();
+	 * WritePolicy wp = client.copyWritePolicyDefault();
+	 * wp.txn = txn;
+	 * client.put(wp, key, new Bin("bin1", "val1"));
+	 * CommitStatus status = client.commit(txn);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param txn	transaction
 	 * @return		status of the commit on success
-	 * @throws AerospikeException.Commit	if verify commit fails
+	 * @throws AerospikeException.Commit	when verify or commit fails
+	 * @see #commit(EventLoop, CommitListener, Txn)
+	 * @see #abort(Txn)
+	 * @see Txn
 	 */
 	public final CommitStatus commit(Txn txn)
 		throws AerospikeException.Commit {
@@ -804,12 +831,28 @@ public final CommitStatus commit(Txn txn)
 	 * The event loop thread will process the command and send the results to the listener.
 	 * <p>
 	 * Requires server version 8.0+
+	 * <p>
+	 * <p>Async commit: put with txn policy then commit via event loop and listener.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Txn txn = new Txn();
+	 * WritePolicy wp = client.copyWritePolicyDefault();
+	 * wp.txn = txn;
+	 * client.put(loop, null, wp, key, new Bin("bin1", "val1"));
+	 * client.commit(loop, new CommitListener() { ... }, txn);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param txn			transaction
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #commit(Txn)
+	 * @see CommitListener
 	 */
 	public final void commit(EventLoop eventLoop, CommitListener listener, Txn txn)
 		throws AerospikeException {
@@ -844,9 +887,24 @@ public final void commit(EventLoop eventLoop, CommitListener listener, Txn txn)
 	 * Abort and rollback the given transaction.
 	 * <p>
 	 * Requires server version 8.0+
+	 * <p>
+	 * <p>Abort a transaction and check returned status.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Txn txn = new Txn();
+	 * WritePolicy wp = client.copyWritePolicyDefault();
+	 * wp.txn = txn;
+	 * client.put(wp, key, new Bin("bin1", "val1"));
+	 * AbortStatus status = client.abort(txn);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param txn	transaction
+	 * @param txn	transaction to abort
 	 * @return		status of the abort
+	 * @throws AerospikeException	when transaction was already committed
+	 * @see #commit(Txn)
+	 * @see #abort(EventLoop, AbortListener, Txn)
+	 * @see Txn
 	 */
 	public final AbortStatus abort(Txn txn) {
 		TxnRoll tr = new TxnRoll(cluster, txn);
@@ -872,12 +930,28 @@ public final AbortStatus abort(Txn txn) {
 	 * The event loop thread will process the command and send the results to the listener.
 	 * <p>
 	 * Requires server version 8.0+
+	 * <p>
+	 * <p>Async abort: put with txn then abort via event loop and AbortListener.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Txn txn = new Txn();
+	 * WritePolicy wp = client.copyWritePolicyDefault();
+	 * wp.txn = txn;
+	 * client.put(loop, null, wp, key, new Bin("bin1", "val1"));
+	 * client.abort(loop, new AbortListener() { ... }, txn);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
-	 * @param txn			transaction
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param txn			transaction to abort
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #abort(Txn)
+	 * @see AbortListener
 	 */
 	public final void abort(EventLoop eventLoop, AbortListener listener, Txn txn)
 		throws AerospikeException {
@@ -908,14 +982,23 @@ public final void abort(EventLoop eventLoop, AbortListener listener, Txn txn)
 	//-------------------------------------------------------
 
 	/**
-	 * Write record bin(s).
-	 * The policy specifies the command timeouts, record expiration and how the command is
-	 * handled when the record already exists.
+	 * Write record bins; policy controls timeout, expiration, and create/replace behavior.
+	 * <p>
+	 * <p>Put bins for a key then get the record.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("ns", "set", "mykey");
+	 * client.put(null, key, new Bin("bin1", "value1"), new Bin("bin2", 42));
+	 * Record rec = client.get(null, key);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if write fails
+	 * @param policy  write configuration, or null for defaults
+	 * @param key     record key
+	 * @param bins    bin name/value pairs
+	 * @throws AerospikeException when write fails
+	 * @see #get(Policy, Key)
+	 * @see #put(EventLoop, WriteListener, WritePolicy, Key, Bin...)
 	 */
 	public final void put(WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -934,20 +1017,26 @@ public final void put(WritePolicy policy, Key key, Bin... bins)
 	}
 
 	/**
-	 * Asynchronously write record bin(s).
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously write record bins.
 	 * <p>
-	 * The policy specifies the command timeout, record expiration and how the command is
-	 * handled when the record already exists.
+	 * <p>Async put via event loop and WriteListener.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.put(loop, writeListener, null, key, new Bin("bin1", "v"));
+	 * }</pre>
 	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results, pass in null for fire and forget
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback, or null for fire-and-forget
+	 * @param policy     write configuration, or null for defaults
+	 * @param key        record key
+	 * @param bins       bin name/value pairs
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #put(WritePolicy, Key, Bin...)
+	 * @see WriteListener
 	 */
 	public final void put(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -970,15 +1059,21 @@ public final void put(EventLoop eventLoop, WriteListener listener, WritePolicy p
 	//-------------------------------------------------------
 
 	/**
-	 * Append bin string values to existing record bin values.
-	 * The policy specifies the command timeout, record expiration and how the command is
-	 * handled when the record already exists.
-	 * This call only works for string values.
+	 * Append string values to existing bin values (strings only).
+	 * <p>
+	 * <p>Append a string to an existing bin.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.append(null, key, new Bin("name", "suffix"));
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if append fails
+	 * @param policy  write configuration, or null for defaults
+	 * @param key     record key
+	 * @param bins    bin name/value pairs
+	 * @throws AerospikeException when append fails
+	 * @see #put(WritePolicy, Key, Bin...)
+	 * @see #append(EventLoop, WriteListener, WritePolicy, Key, Bin...)
 	 */
 	public final void append(WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -997,21 +1092,25 @@ public final void append(WritePolicy policy, Key key, Bin... bins)
 	}
 
 	/**
-	 * Asynchronously append bin string values to existing record bin values.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously append string values to existing bin values.
 	 * <p>
-	 * The policy specifies the command timeout, record expiration and how the command is
-	 * handled when the record already exists.
-	 * This call only works for string values.
+	 * <p>Async append via event loop and WriteListener.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.append(loop, listener, null, key, new Bin("name", "suffix"));
+	 * }</pre>
 	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results, pass in null for fire and forget
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback, or null for fire-and-forget
+	 * @param policy     write configuration, or null for defaults
+	 * @param key        record key
+	 * @param bins       bin name/value pairs
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #append(WritePolicy, Key, Bin...)
 	 */
 	public final void append(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -1030,15 +1129,21 @@ public final void append(EventLoop eventLoop, WriteListener listener, WritePolic
 	}
 
 	/**
-	 * Prepend bin string values to existing record bin values.
-	 * The policy specifies the command timeout, record expiration and how the command is
-	 * handled when the record already exists.
-	 * This call works only for string values.
+	 * Prepend string values to existing bin values (strings only).
+	 * <p>
+	 * <p>Prepend a string to an existing bin.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.prepend(null, key, new Bin("name", "prefix"));
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if prepend fails
+	 * @param policy  write configuration, or null for defaults
+	 * @param key     record key
+	 * @param bins    bin name/value pairs
+	 * @throws AerospikeException when prepend fails
+	 * @see #append(WritePolicy, Key, Bin...)
+	 * @see #prepend(EventLoop, WriteListener, WritePolicy, Key, Bin...)
 	 */
 	public final void prepend(WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -1057,21 +1162,26 @@ public final void prepend(WritePolicy policy, Key key, Bin... bins)
 	}
 
 	/**
-	 * Asynchronously prepend bin string values to existing record bin values.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously prepend string values to existing bin values.
 	 * <p>
-	 * The policy specifies the command timeout, record expiration and how the command is
-	 * handled when the record already exists.
-	 * This call only works for string values.
+	 * <p>Async prepend via event loop and WriteListener.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key key = new Key("ns", "set", "prependkey");
+	 * client.prepend(loop, listener, null, key, new Bin("prependbin", "Hello "));
+	 * }</pre>
 	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results, pass in null for fire and forget
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback, or null for fire-and-forget
+	 * @param policy     write configuration, or null for defaults
+	 * @param key        record key
+	 * @param bins       bin name/value pairs
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #prepend(WritePolicy, Key, Bin...)
 	 */
 	public final void prepend(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -1094,15 +1204,21 @@ public final void prepend(EventLoop eventLoop, WriteListener listener, WritePoli
 	//-------------------------------------------------------
 
 	/**
-	 * Add integer/double bin values to record bin values. If the record or bin does not exist, the
-	 * record/bin will be created by default with the value to be added. The policy specifies the
-	 * command timeout, record expiration and how the command is handled when the record
-	 * already exists.
+	 * Add integer/double bin values to existing bins; creates record/bin if absent.
+	 * <p>
+	 * <p>Add an integer to a bin (creates bin if absent).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.add(null, key, new Bin("counter", 1));
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if add fails
+	 * @param policy  write configuration, or null for defaults
+	 * @param key     record key
+	 * @param bins    bin name/value pairs (integer or double)
+	 * @throws AerospikeException when add fails
+	 * @see #operate(WritePolicy, Key, Operation...)
+	 * @see #add(EventLoop, WriteListener, WritePolicy, Key, Bin...)
 	 */
 	public final void add(WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -1121,21 +1237,26 @@ public final void add(WritePolicy policy, Key key, Bin... bins)
 	}
 
 	/**
-	 * Asynchronously add integer/double bin values to record bin values. If the record or bin does
-	 * not exist, the record/bin will be created by default with the value to be added. The policy
-	 * specifies the command timeout, record expiration and how the command is handled when
-	 * the record already exists.
+	 * Asynchronously add integer/double bin values to existing values.
 	 * <p>
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * <p>Async add via event loop and WriteListener.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key key = new Key("ns", "set", "addkey");
+	 * client.add(loop, listener, null, key, new Bin("addbin", 10));
+	 * }</pre>
 	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results, pass in null for fire and forget
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @param bins					array of bin name/value pairs
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback, or null for fire-and-forget
+	 * @param policy     write configuration, or null for defaults
+	 * @param key        record key
+	 * @param bins       bin name/value pairs (integer or double)
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #add(WritePolicy, Key, Bin...)
 	 */
 	public final void add(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key, Bin... bins)
 		throws AerospikeException {
@@ -1158,13 +1279,21 @@ public final void add(EventLoop eventLoop, WriteListener listener, WritePolicy p
 	//-------------------------------------------------------
 
 	/**
-	 * Delete record for specified key.
-	 * The policy specifies the command timeout.
+	 * Delete the record for the given key.
+	 * <p>
+	 * <p>Delete a record and check if it existed.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * boolean existed = client.delete(null, key);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				delete configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @return						whether record existed on server before deletion
-	 * @throws AerospikeException	if delete fails
+	 * @param policy  write configuration, or null for defaults
+	 * @param key     record key
+	 * @return        true if record existed before deletion
+	 * @throws AerospikeException when delete fails
+	 * @see #delete(BatchPolicy, BatchDeletePolicy, Key[])
+	 * @see #delete(EventLoop, DeleteListener, WritePolicy, Key)
 	 */
 	public final boolean delete(WritePolicy policy, Key key)
 		throws AerospikeException {
@@ -1184,18 +1313,26 @@ public final boolean delete(WritePolicy policy, Key key)
 	}
 
 	/**
-	 * Asynchronously delete record for specified key.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously delete the record for the given key.
 	 * <p>
-	 * The policy specifies the command timeout.
+	 * <p>Async delete via event loop and DeleteListener.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key key = new Key("ns", "set", "delkey");
+	 * client.delete(loop, new DeleteListener() { ... }, null, key);
+	 * }</pre>
 	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results, pass in null for fire and forget
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback, or null for fire-and-forget
+	 * @param policy     write configuration, or null for defaults
+	 * @param key        record key
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #delete(WritePolicy, Key)
+	 * @see DeleteListener
 	 */
 	public final void delete(EventLoop eventLoop, DeleteListener listener, WritePolicy policy, Key key)
 		throws AerospikeException {
@@ -1214,15 +1351,25 @@ public final void delete(EventLoop eventLoop, DeleteListener listener, WritePoli
 	}
 
 	/**
-	 * Delete records for specified keys. If a key is not found, the corresponding result
-	 * {@link BatchRecord#resultCode} will be {@link ResultCode#KEY_NOT_FOUND_ERROR}.
+	 * Delete records for the given keys in a single batch; missing keys get {@link ResultCode#KEY_NOT_FOUND_ERROR}.
+	 * <p>
+	 * Requires server 6.0+.
 	 * <p>
-	 * Requires server version 6.0+
+	 * <p>Batch delete keys and get results per key.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * BatchResults results = client.delete(null, null, keys);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param batchPolicy	batch configuration parameters, pass in null for defaults
-	 * @param deletePolicy	delete configuration parameters, pass in null for defaults
-	 * @param keys			array of unique record identifiers
-	 * @throws AerospikeException.BatchRecordArray	which contains results for keys that did complete
+	 * @param batchPolicy  batch configuration, or null for defaults
+	 * @param deletePolicy delete configuration, or null for defaults
+	 * @param keys         keys to delete
+	 * @return             results per key
+	 * @throws AerospikeException.BatchRecordArray when some keys fail (contains partial results)
+	 * @see #delete(WritePolicy, Key)
+	 * @see #operate(BatchPolicy, List)
 	 */
 	public final BatchResults delete(BatchPolicy batchPolicy, BatchDeletePolicy deletePolicy, Key[] keys)
 		throws AerospikeException {
@@ -1282,22 +1429,29 @@ public final BatchResults delete(BatchPolicy batchPolicy, BatchDeletePolicy dele
 	}
 
 	/**
-	 * Asynchronously delete records for specified keys.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously delete records for the given keys; results delivered to listener as a single array.
 	 * <p>
-	 * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
-	 * {@link ResultCode#KEY_NOT_FOUND_ERROR}.
-	 * <p>
-	 * Requires server version 6.0+
+	 * Missing keys set {@link BatchRecord#resultCode} to {@link ResultCode#KEY_NOT_FOUND_ERROR}. Requires server 6.0+.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.delete(loop, new BatchRecordArrayListener() { ... }, null, null, keys);
+	 * }</pre>
 	 *
-	 * @param eventLoop		event loop that will process the command. If NULL, the event
-	 * 						loop will be chosen by round-robin.
-	 * @param listener		where to send results
-	 * @param batchPolicy	batch configuration parameters, pass in null for defaults
-	 * @param deletePolicy	delete configuration parameters, pass in null for defaults
-	 * @param keys			array of unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop    event loop; null to use round-robin
+	 * @param listener     callback for batch results
+	 * @param batchPolicy  batch configuration, or null for defaults
+	 * @param deletePolicy delete configuration, or null for defaults
+	 * @param keys         keys to delete
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #delete(BatchPolicy, BatchDeletePolicy, Key[])
+	 * @see #delete(EventLoop, BatchRecordSequenceListener, BatchPolicy, BatchDeletePolicy, Key[])
+	 * @see BatchRecordArrayListener
 	 */
 	public final void delete(
 		EventLoop eventLoop,
@@ -1357,23 +1511,29 @@ public final void delete(
 	}
 
 	/**
-	 * Asynchronously delete records for specified keys.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
-	 * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
-	 * {@link ResultCode#KEY_NOT_FOUND_ERROR}.
+	 * Asynchronously delete records for the given keys; each result delivered via onRecord.
 	 * <p>
-	 * Requires server version 6.0+
+	 * Missing keys set {@link BatchRecord#resultCode} to {@link ResultCode#KEY_NOT_FOUND_ERROR}. Requires server 6.0+.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.delete(loop, new BatchRecordSequenceListener() { ... }, null, null, keys);
+	 * }</pre>
 	 *
-	 * @param eventLoop		event loop that will process the command. If NULL, the event
-	 * 						loop will be chosen by round-robin.
-	 * @param listener		where to send results
-	 * @param batchPolicy	batch configuration parameters, pass in null for defaults
-	 * @param deletePolicy	delete configuration parameters, pass in null for defaults
-	 * @param keys			array of unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop    event loop; null to use round-robin
+	 * @param listener     callback for per-record results
+	 * @param batchPolicy  batch configuration, or null for defaults
+	 * @param deletePolicy delete configuration, or null for defaults
+	 * @param keys         keys to delete
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #delete(BatchPolicy, BatchDeletePolicy, Key[])
+	 * @see #delete(EventLoop, BatchRecordArrayListener, BatchPolicy, BatchDeletePolicy, Key[])
+	 * @see BatchRecordSequenceListener
 	 */
 	public final void delete(
 		EventLoop eventLoop,
@@ -1428,22 +1588,23 @@ public final void delete(
 	}
 
 	/**
-	 * Remove records in specified namespace/set efficiently.  This method is many orders of magnitude
-	 * faster than deleting records one at a time.
+	 * Remove records in namespace/set efficiently; many orders of magnitude faster than deleting one at a time.
 	 * <p>
-	 * See <a href="https://www.aerospike.com/docs/reference/info#truncate">https://www.aerospike.com/docs/reference/info#truncate</a>
-	 * <p>
-	 * This asynchronous server call may return before the truncation is complete.  The user can still
-	 * write new records after the server call returns because new records will have last update times
-	 * greater than the truncate cutoff (set at the time of truncate call).
+	 * Server call may return before truncation completes; new writes use last-update times after the cutoff.
+	 * <p>Truncate a set in a namespace.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.truncate(null, "ns", "set1", null);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				info command configuration parameters, pass in null for defaults
-	 * @param ns					required namespace
-	 * @param set					optional set name.  Pass in null to delete all sets in namespace.
-	 * @param beforeLastUpdate		optional delete records before record last update time.
-	 * 								If specified, value must be before the current time.
-	 * 								Pass in null to delete all records in namespace/set.
-	 * @throws AerospikeException	if truncate fails
+	 * @param policy             info configuration, or null for defaults
+	 * @param ns                 namespace
+	 * @param set                set name, or null for all sets in namespace
+	 * @param beforeLastUpdate    delete records before this time, or null for all
+	 * @throws AerospikeException when truncate fails
+	 * @see <a href="https://www.aerospike.com/docs/reference/info#truncate">truncate</a>
+	 * @see #delete(WritePolicy, Key)
 	 */
 	public final void truncate(InfoPolicy policy, String ns, String set, Calendar beforeLastUpdate)
 		throws AerospikeException {
@@ -1485,13 +1646,19 @@ public final void truncate(InfoPolicy policy, String ns, String set, Calendar be
 	//-------------------------------------------------------
 
 	/**
-	 * Reset record's time to expiration using the policy's expiration.
-	 * If the record does not exist, it can't be created because the server deletes empty records.
-	 * Throw an exception if the record does not exist.
+	 * Reset record time-to-expiration using the policy; fails when the record does not exist.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.touch(null, key);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @throws AerospikeException	if touch fails
+	 * @param policy             write configuration, or null for defaults
+	 * @param key                record key
+	 * @throws AerospikeException when touch fails or record does not exist
+	 * @see #touched(WritePolicy, Key)
+	 * @see #touch(EventLoop, WriteListener, WritePolicy, Key)
 	 */
 	public final void touch(WritePolicy policy, Key key)
 		throws AerospikeException {
@@ -1510,20 +1677,15 @@ public final void touch(WritePolicy policy, Key key)
 	}
 
 	/**
-	 * Asynchronously reset record's time to expiration using the policy's expiration.
-	 * If the record does not exist, it can't be created because the server deletes empty records.
+	 * Asynchronously reset record time-to-expiration using the policy.
 	 * <p>
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Fail if the record does not exist.
-	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results, pass in null for fire and forget
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback, or null for fire-and-forget
+	 * @param policy     write configuration, or null for defaults
+	 * @param key        record key
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #touch(WritePolicy, Key)
+	 * @see WriteListener
 	 */
 	public final void touch(EventLoop eventLoop, WriteListener listener, WritePolicy policy, Key key)
 		throws AerospikeException {
@@ -1542,13 +1704,20 @@ public final void touch(EventLoop eventLoop, WriteListener listener, WritePolicy
 	}
 
 	/**
-	 * Reset record's time to expiration using the policy's expiration.
-	 * If the record does not exist, it can't be created because the server deletes empty records.
-	 * Return true if the record exists and is touched. Return false if the record does not exist.
+	 * Reset record time-to-expiration; returns true if record existed and was touched, false if not found.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * boolean ok = client.touched(null, key);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @throws AerospikeException	if touch fails
+	 * @param policy             write configuration, or null for defaults
+	 * @param key                record key
+	 * @return                   true if touched, false if record did not exist
+	 * @throws AerospikeException when command fails
+	 * @see #touch(WritePolicy, Key)
+	 * @see #touched(EventLoop, ExistsListener, WritePolicy, Key)
 	 */
 	public final boolean touched(WritePolicy policy, Key key)
 		throws AerospikeException {
@@ -1568,21 +1737,25 @@ public final boolean touched(WritePolicy policy, Key key)
 	}
 
 	/**
-	 * Asynchronously reset record's time to expiration using the policy's expiration.
-	 * If the record does not exist, it can't be created because the server deletes empty records.
-	 * <p>
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * If the record does not exist, send a value of false to
-	 * {@link com.aerospike.client.listener.ExistsListener#onSuccess(Key, boolean)}
+	 * Asynchronously reset record time-to-expiration; listener receives false when record does not exist.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key key = new Key("ns", "set", "touchkey");
+	 * client.touched(loop, new ExistsListener() { ... }, null, key);
+	 * }</pre>
 	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results, pass in null for fire and forget
-	 * @param policy				write configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback
+	 * @param policy     write configuration, or null for defaults
+	 * @param key        record key
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #touched(WritePolicy, Key)
+	 * @see ExistsListener
 	 */
 	public final void touched(EventLoop eventLoop, ExistsListener listener, WritePolicy policy, Key key)
 		throws AerospikeException {
@@ -1605,13 +1778,21 @@ public final void touched(EventLoop eventLoop, ExistsListener listener, WritePol
 	//-------------------------------------------------------
 
 	/**
-	 * Determine if a record key exists.
-	 * The policy can be used to specify timeouts.
+	 * Check whether a record key exists.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * boolean found = client.exists(null, key);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy				generic configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @return						whether record exists or not
-	 * @throws AerospikeException	if command fails
+	 * @param policy             read configuration, or null for defaults
+	 * @param key                record key
+	 * @return                   true if record exists
+	 * @throws AerospikeException when command fails
+	 * @see #get(Policy, Key)
+	 * @see #exists(BatchPolicy, Key[])
+	 * @see #exists(EventLoop, ExistsListener, Policy, Key)
 	 */
 	public final boolean exists(Policy policy, Key key)
 		throws AerospikeException {
@@ -1631,18 +1812,25 @@ public final boolean exists(Policy policy, Key key)
 	}
 
 	/**
-	 * Asynchronously determine if a record key exists.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The policy can be used to specify timeouts.
+	 * Asynchronously check whether a record key exists.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key key = new Key("ns", "set", "existskey");
+	 * client.exists(loop, new ExistsListener() { ... }, null, key);
+	 * }</pre>
 	 *
-	 * @param eventLoop				event loop that will process the command. If NULL, the event
-	 * 								loop will be chosen by round-robin.
-	 * @param listener				where to send results
-	 * @param policy				generic configuration parameters, pass in null for defaults
-	 * @param key					unique record identifier
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param eventLoop  event loop; null to use round-robin
+	 * @param listener   callback
+	 * @param policy     read configuration, or null for defaults
+	 * @param key        record key
+	 * @throws AerospikeException when event loop registration fails
+	 * @see #exists(Policy, Key)
+	 * @see ExistsListener
 	 */
 	public final void exists(EventLoop eventLoop, ExistsListener listener, Policy policy, Key key)
 		throws AerospikeException {
@@ -1665,13 +1853,21 @@ public final void exists(EventLoop eventLoop, ExistsListener listener, Policy po
 	}
 
 	/**
-	 * Check if multiple record keys exist in one batch call.
-	 * The returned boolean array is in positional order with the original key array order.
+	 * Check if multiple record keys exist in one batch call; result array matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * boolean[] found = client.exists(null, keys);
+	 * client.close();
+	 * }</pre>
 	 *
-	 * @param policy	batch configuration parameters, pass in null for defaults
-	 * @param keys		array of unique record identifiers
-	 * @return			array key/existence status pairs
-	 * @throws AerospikeException.BatchExists	which contains results for keys that did complete
+	 * @param policy  batch configuration, or null for defaults
+	 * @param keys    keys to check
+	 * @return        existence per key, same order as keys
+	 * @throws AerospikeException.BatchExists when some keys fail (contains partial results)
+	 * @see #exists(Policy, Key)
+	 * @see #exists(EventLoop, ExistsArrayListener, BatchPolicy, Key[])
 	 */
 	public final boolean[] exists(BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -1717,18 +1913,29 @@ public final boolean[] exists(BatchPolicy policy, Key[] keys)
 	}
 
 	/**
-	 * Asynchronously check if multiple record keys exist in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously check if multiple record keys exist in one batch call; results in one callback as array.
 	 * <p>
-	 * The returned boolean array is in positional order with the original key array order.
+	 * Result array order matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.exists(loop, new ExistsArrayListener() { ... }, null, keys);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #exists(BatchPolicy, Key[])
+	 * @see #exists(EventLoop, ExistsSequenceListener, BatchPolicy, Key[])
+	 * @see ExistsArrayListener
 	 */
 	public final void exists(EventLoop eventLoop, ExistsArrayListener listener, BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -1773,18 +1980,28 @@ public final void exists(EventLoop eventLoop, ExistsArrayListener listener, Batc
 	}
 
 	/**
-	 * Asynchronously check if multiple record keys exist in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously check if multiple record keys exist in one batch call; each result via onExists().
 	 * <p>
-	 * Each key's result is returned in separate onExists() calls.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.exists(loop, new ExistsSequenceListener() { ... }, null, keys);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #exists(BatchPolicy, Key[])
+	 * @see #exists(EventLoop, ExistsArrayListener, BatchPolicy, Key[])
+	 * @see ExistsSequenceListener
 	 */
 	public final void exists(EventLoop eventLoop, ExistsSequenceListener listener, BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -1833,12 +2050,21 @@ public final void exists(EventLoop eventLoop, ExistsSequenceListener listener, B
 
 	/**
 	 * Read entire record for specified key.
-	 * The policy can be used to specify timeouts.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("ns", "set", "mykey");
+	 * Record rec = client.get(null, key);
+	 * if (rec != null) { String s = rec.getString("bin1"); }
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
 	 * @return						if found, return record instance.  If not found, return null.
-	 * @throws AerospikeException	if read fails
+	 * @throws AerospikeException	when read fails
+	 * @see #get(Policy, Key, String...)
+	 * @see #get(EventLoop, RecordListener, Policy, Key)
 	 */
 	public final Record get(Policy policy, Key key)
 		throws AerospikeException {
@@ -1859,17 +2085,25 @@ public final Record get(Policy policy, Key key)
 
 	/**
 	 * Asynchronously read entire record for specified key.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The policy can be used to specify timeouts.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key key = new Key("ns", "set", "mykey");
+	 * client.get(loop, new RecordListener() { ... }, null, key);
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
 	 * @param listener				where to send results
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(Policy, Key)
+	 * @see RecordListener
 	 */
 	public final void get(EventLoop eventLoop, RecordListener listener, Policy policy, Key key)
 		throws AerospikeException {
@@ -1892,14 +2126,22 @@ public final void get(EventLoop eventLoop, RecordListener listener, Policy polic
 	}
 
 	/**
-	 * Read record header and bins for specified key.
-	 * The policy can be used to specify timeouts.
+	 * Read record header and bins for specified key and bin names.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("ns", "set", "mykey");
+	 * Record rec = client.get(null, key, "bin1", "bin2");
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
 	 * @param binNames				bins to retrieve
 	 * @return						if found, return record instance.  If not found, return null.
-	 * @throws AerospikeException	if read fails
+	 * @throws AerospikeException	when read fails
+	 * @see #get(Policy, Key)
+	 * @see #get(EventLoop, RecordListener, Policy, Key, String...)
 	 */
 	public final Record get(Policy policy, Key key, String... binNames)
 		throws AerospikeException {
@@ -1919,11 +2161,16 @@ public final Record get(Policy policy, Key key, String... binNames)
 	}
 
 	/**
-	 * Asynchronously read record header and bins for specified key.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The policy can be used to specify timeouts.
+	 * Asynchronously read record header and bins for specified key and bin names.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.get(loop, new RecordListener() { ... }, null, key, "bin1", "bin2");
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
@@ -1931,7 +2178,9 @@ public final Record get(Policy policy, Key key, String... binNames)
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
 	 * @param binNames				bins to retrieve
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(Policy, Key, String...)
+	 * @see RecordListener
 	 */
 	public final void get(EventLoop eventLoop, RecordListener listener, Policy policy, Key key, String... binNames)
 		throws AerospikeException {
@@ -1954,13 +2203,21 @@ public final void get(EventLoop eventLoop, RecordListener listener, Policy polic
 	}
 
 	/**
-	 * Read record generation and expiration only for specified key.  Bins are not read.
-	 * The policy can be used to specify timeouts.
+	 * Read record generation and expiration only; bins are not read.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("ns", "set", "mykey");
+	 * Record rec = client.getHeader(null, key);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
 	 * @return						if found, return record instance.  If not found, return null.
-	 * @throws AerospikeException	if read fails
+	 * @throws AerospikeException	when read fails
+	 * @see #get(Policy, Key)
+	 * @see #getHeader(EventLoop, RecordListener, Policy, Key)
 	 */
 	public final Record getHeader(Policy policy, Key key)
 		throws AerospikeException {
@@ -1980,18 +2237,25 @@ public final Record getHeader(Policy policy, Key key)
 	}
 
 	/**
-	 * Asynchronously read record generation and expiration only for specified key.  Bins are not read.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The policy can be used to specify timeouts.
+	 * Asynchronously read record generation and expiration only; bins are not read.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.getHeader(loop, new RecordListener() { ... }, null, key);
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
 	 * @param listener				where to send results
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #getHeader(Policy, Key)
+	 * @see RecordListener
 	 */
 	public final void getHeader(EventLoop eventLoop, RecordListener listener, Policy policy, Key key)
 		throws AerospikeException {
@@ -2018,16 +2282,26 @@ public final void getHeader(EventLoop eventLoop, RecordListener listener, Policy
 	//-------------------------------------------------------
 
 	/**
-	 * Read multiple records for specified batch keys in one batch call.
-	 * This method allows different namespaces/bins to be requested for each key in the batch.
-	 * The returned records are located in the same list.
-	 * If the BatchRead key field is not found, the corresponding record field will be null.
+	 * Read multiple records for specified batch keys in one batch call; different bins per key allowed.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * List batchReads = java.util.Arrays.asList(
+	 *   new BatchRead(new Key("ns", "set", "k1"), "bin1"),
+	 *   new BatchRead(new Key("ns", "set", "k2"))
+	 * );
+	 * client.get(null, batchReads);
+	 * for (BatchRead br : batchReads) { Record r = br.record; }
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy	batch configuration parameters, pass in null for defaults
 	 * @param records	list of unique record identifiers and the bins to retrieve.
 	 *					The returned records are located in the same list.
 	 * @return			true if all batch key requests succeeded
-	 * @throws AerospikeException	if read fails
+	 * @throws AerospikeException	when read fails
+	 * @see #get(BatchPolicy, Key[])
+	 * @see #get(EventLoop, BatchListListener, BatchPolicy, List)
 	 */
 	public final boolean get(BatchPolicy policy, List<BatchRead> records)
 		throws AerospikeException {
@@ -2064,13 +2338,17 @@ public final boolean get(BatchPolicy policy, List<BatchRead> records)
 	}
 
 	/**
-	 * Asynchronously read multiple records for specified batch keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * This method allows different namespaces/bins to be requested for each key in the batch.
-	 * The returned records are located in the same list.
-	 * If the BatchRead key field is not found, the corresponding record field will be null.
+	 * Asynchronously read multiple records for specified batch keys; results in the same list.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * List batchReads = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")), new BatchRead(new Key("ns", "set", "k2")));
+	 * client.get(loop, new BatchListListener() { ... }, null, batchReads);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -2078,7 +2356,9 @@ public final boolean get(BatchPolicy policy, List<BatchRead> records)
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param records		list of unique record identifiers and the bins to retrieve.
 	 *						The returned records are located in the same list.
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, List)
+	 * @see BatchListListener
 	 */
 	public final void get(EventLoop eventLoop, BatchListListener listener, BatchPolicy policy, List<BatchRead> records)
 		throws AerospikeException {
@@ -2119,13 +2399,17 @@ public final void get(EventLoop eventLoop, BatchListListener listener, BatchPoli
 	}
 
 	/**
-	 * Asynchronously read multiple records for specified batch keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * This method allows different namespaces/bins to be requested for each key in the batch.
-	 * Each record result is returned in separate onRecord() calls.
-	 * If the BatchRead key field is not found, the corresponding record field will be null.
+	 * Asynchronously read multiple records for specified batch keys; each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * List batchReads = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")), new BatchRead(new Key("ns", "set", "k2")));
+	 * client.get(loop, new BatchSequenceListener() { ... }, null, batchReads);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -2133,7 +2417,9 @@ public final void get(EventLoop eventLoop, BatchListListener listener, BatchPoli
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param records		list of unique record identifiers and the bins to retrieve.
 	 *						The returned records are located in the same list.
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, List)
+	 * @see BatchSequenceListener
 	 */
 	public final void get(EventLoop eventLoop, BatchSequenceListener listener, BatchPolicy policy, List<BatchRead> records)
 		throws AerospikeException {
@@ -2176,14 +2462,21 @@ public final void get(EventLoop eventLoop, BatchSequenceListener listener, Batch
 	}
 
 	/**
-	 * Read multiple records for specified keys in one batch call.
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Read multiple records for specified keys in one batch call; result order matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * Record[] records = client.get(null, keys);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy	batch configuration parameters, pass in null for defaults
 	 * @param keys		array of unique record identifiers
-	 * @return			array of records
-	 * @throws AerospikeException.BatchRecords	which contains results for keys that did complete
+	 * @return			array of records (null for missing keys)
+	 * @throws AerospikeException.BatchRecords	when some keys fail (contains partial results)
+	 * @see #get(BatchPolicy, List)
+	 * @see #get(EventLoop, RecordArrayListener, BatchPolicy, Key[])
 	 */
 	public final Record[] get(BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -2230,19 +2523,26 @@ public final Record[] get(BatchPolicy policy, Key[] keys)
 	}
 
 	/**
-	 * Asynchronously read multiple records for specified keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Asynchronously read multiple records for specified keys; results in one callback as array.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.get(loop, new RecordArrayListener() { ... }, null, keys);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, Key[])
+	 * @see RecordArrayListener
 	 */
 	public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -2287,19 +2587,26 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
 	}
 
 	/**
-	 * Asynchronously read multiple records for specified keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
-	 * If a key is not found, the record will be null.
+	 * Asynchronously read multiple records for specified keys; each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.get(loop, new RecordSequenceListener() { ... }, null, keys);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, Key[])
+	 * @see RecordSequenceListener
 	 */
 	public final void get(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -2343,15 +2650,22 @@ public final void get(EventLoop eventLoop, RecordSequenceListener listener, Batc
 	}
 
 	/**
-	 * Read multiple record headers and bins for specified keys in one batch call.
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Read multiple records for specified keys and bin names; result order matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * Record[] records = client.get(null, keys, "bin1");
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy	batch configuration parameters, pass in null for defaults
 	 * @param keys		array of unique record identifiers
 	 * @param binNames	array of bins to retrieve
-	 * @return			array of records
-	 * @throws AerospikeException.BatchRecords	which contains results for keys that did complete
+	 * @return			array of records (null for missing keys)
+	 * @throws AerospikeException.BatchRecords	when some keys fail (contains partial results)
+	 * @see #get(BatchPolicy, Key[])
+	 * @see #get(EventLoop, RecordArrayListener, BatchPolicy, Key[], String...)
 	 */
 	public final Record[] get(BatchPolicy policy, Key[] keys, String... binNames)
 		throws AerospikeException {
@@ -2400,12 +2714,17 @@ public final Record[] get(BatchPolicy policy, Key[] keys, String... binNames)
 	}
 
 	/**
-	 * Asynchronously read multiple record headers and bins for specified keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Asynchronously read multiple records for specified keys and bin names; results in one callback.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.get(loop, new RecordArrayListener() { ... }, null, keys, "bin1");
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -2413,7 +2732,9 @@ public final Record[] get(BatchPolicy policy, Key[] keys, String... binNames)
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
 	 * @param binNames		array of bins to retrieve
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, Key[], String...)
+	 * @see RecordArrayListener
 	 */
 	public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys, String... binNames)
 		throws AerospikeException {
@@ -2461,12 +2782,17 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
 	}
 
 	/**
-	 * Asynchronously read multiple record headers and bins for specified keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
-	 * If a key is not found, the record will be null.
+	 * Asynchronously read multiple records for specified keys and bin names; each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.get(loop, new RecordSequenceListener() { ... }, null, keys, "bin1");
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -2474,7 +2800,9 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
 	 * @param binNames		array of bins to retrieve
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, Key[], String...)
+	 * @see RecordSequenceListener
 	 */
 	public final void get(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys, String... binNames)
 		throws AerospikeException {
@@ -2520,15 +2848,22 @@ public final void get(EventLoop eventLoop, RecordSequenceListener listener, Batc
 	}
 
 	/**
-	 * Read multiple records for specified keys using read operations in one batch call.
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Read multiple records for specified keys using read operations; result order matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * Record[] records = client.get(null, keys, Operation.get("bin1"));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy	batch configuration parameters, pass in null for defaults
 	 * @param keys		array of unique record identifiers
 	 * @param ops		array of read operations on record
-	 * @return			array of records
-	 * @throws AerospikeException.BatchRecords	which contains results for keys that did complete
+	 * @return			array of records (null for missing keys)
+	 * @throws AerospikeException.BatchRecords	when some keys fail (contains partial results)
+	 * @see #get(BatchPolicy, Key[])
+	 * @see Operation
 	 */
 	public final Record[] get(BatchPolicy policy, Key[] keys, Operation... ops)
 		throws AerospikeException {
@@ -2574,12 +2909,17 @@ public final Record[] get(BatchPolicy policy, Key[] keys, Operation... ops)
 	}
 
 	/**
-	 * Asynchronously read multiple records for specified keys using read operations in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Asynchronously read multiple records for specified keys using read operations; results in one callback.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.get(loop, new RecordArrayListener() { ... }, null, keys, Operation.get("bin1"));
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -2587,7 +2927,9 @@ public final Record[] get(BatchPolicy policy, Key[] keys, Operation... ops)
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
 	 * @param ops			array of read operations on record
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, Key[], Operation...)
+	 * @see RecordArrayListener
 	 */
 	public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys, Operation... ops)
 		throws AerospikeException {
@@ -2632,12 +2974,17 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
 	}
 
 	/**
-	 * Asynchronously read multiple records for specified keys using read operations in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
-	 * If a key is not found, the record will be null.
+	 * Asynchronously read multiple records for specified keys using read operations; each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.get(loop, new RecordSequenceListener() { ... }, null, keys, Operation.get("bin1"));
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -2645,7 +2992,9 @@ public final void get(EventLoop eventLoop, RecordArrayListener listener, BatchPo
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
 	 * @param ops			array of read operations on record
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #get(BatchPolicy, Key[], Operation...)
+	 * @see RecordSequenceListener
 	 */
 	public final void get(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys, Operation... ops)
 		throws AerospikeException {
@@ -2688,14 +3037,21 @@ public final void get(EventLoop eventLoop, RecordSequenceListener listener, Batc
 	}
 
 	/**
-	 * Read multiple record header data for specified keys in one batch call.
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Read multiple record headers (metadata only) for specified keys; result order matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * Record[] headers = client.getHeader(null, keys);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy	batch configuration parameters, pass in null for defaults
 	 * @param keys		array of unique record identifiers
-	 * @return			array of records
-	 * @throws AerospikeException.BatchRecords	which contains results for keys that did complete
+	 * @return			array of records (metadata only; null for missing keys)
+	 * @throws AerospikeException.BatchRecords	when some keys fail (contains partial results)
+	 * @see #getHeader(Policy, Key)
+	 * @see #get(BatchPolicy, Key[])
 	 */
 	public final Record[] getHeader(BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -2742,19 +3098,26 @@ public final Record[] getHeader(BatchPolicy policy, Key[] keys)
 	}
 
 	/**
-	 * Asynchronously read multiple record header data for specified keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The returned records are in positional order with the original key array order.
-	 * If a key is not found, the positional record will be null.
+	 * Asynchronously read multiple record headers (metadata only); results in one callback.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.getHeader(loop, new RecordArrayListener() { ... }, null, keys);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #getHeader(BatchPolicy, Key[])
+	 * @see RecordArrayListener
 	 */
 	public final void getHeader(EventLoop eventLoop, RecordArrayListener listener, BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -2800,19 +3163,26 @@ public final void getHeader(EventLoop eventLoop, RecordArrayListener listener, B
 	}
 
 	/**
-	 * Asynchronously read multiple record header data for specified keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
-	 * If a key is not found, the record will be null.
+	 * Asynchronously read multiple record headers (metadata only); each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.getHeader(loop, new RecordSequenceListener() { ... }, null, keys);
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #getHeader(BatchPolicy, Key[])
+	 * @see RecordSequenceListener
 	 */
 	public final void getHeader(EventLoop eventLoop, RecordSequenceListener listener, BatchPolicy policy, Key[] keys)
 		throws AerospikeException {
@@ -2860,22 +3230,27 @@ public final void getHeader(EventLoop eventLoop, RecordSequenceListener listener
 	//-------------------------------------------------------
 
 	/**
-	 * Perform multiple read/write operations on a single key in one batch call.
-	 * An example would be to add an integer value to an existing record and then
-	 * read the result, all in one database call.
+	 * Perform multiple read/write operations on a single key in one call.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("ns", "set", "mykey");
+	 * Record rec = client.operate(null, key, Operation.add(new Bin("ctr", 1)), Operation.get("ctr"));
+	 * client.close();
+	 * }</pre>
 	 * <p>
 	 * The server executes operations in the same order as the operations array.
 	 * Both scalar bin operations (Operation) and CDT bin operations (ListOperation,
 	 * MapOperation) can be performed in same call.
-	 * <p>
 	 * Operation results are stored with their associated bin name in the returned record.
-	 * The bin's result type will be a list when multiple operations occur on the same bin.
 	 *
 	 * @param policy				write configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
 	 * @param operations			database operations to perform
-	 * @return						record results
-	 * @throws AerospikeException	if command fails
+	 * @return						record with operation results
+	 * @throws AerospikeException	when command fails
+	 * @see #operate(EventLoop, RecordListener, WritePolicy, Key, Operation...)
+	 * @see Operation
 	 */
 	public final Record operate(WritePolicy policy, Key key, Operation... operations)
 		throws AerospikeException {
@@ -2907,19 +3282,16 @@ public final Record operate(WritePolicy policy, Key key, Operation... operations
 	}
 
 	/**
-	 * Asynchronously perform multiple read/write operations on a single key in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * An example would be to add an integer value to an existing record and then
-	 * read the result, all in one database call.
-	 * <p>
-	 * The server executes operations in the same order as the operations array.
-	 * Both scalar bin operations (Operation) and CDT bin operations (ListOperation,
-	 * MapOperation) can be performed in same call.
-	 * <p>
-	 * Operation results are stored with their associated bin name in the returned record.
-	 * The bin's result type will be a list when multiple operations occur on the same bin.
+	 * Asynchronously perform multiple read/write operations on a single key in one call.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.operate(loop, recordListener, null, key, Operation.add(new Bin("ctr", 1)), Operation.get("ctr"));
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
@@ -2927,7 +3299,9 @@ public final Record operate(WritePolicy policy, Key key, Operation... operations
 	 * @param policy				write configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
 	 * @param operations			database operations to perform
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #operate(WritePolicy, Key, Operation...)
+	 * @see RecordListener
 	 */
 	public final void operate(EventLoop eventLoop, RecordListener listener, WritePolicy policy, Key key, Operation... operations)
 		throws AerospikeException {
@@ -2961,19 +3335,26 @@ public final void operate(EventLoop eventLoop, RecordListener listener, WritePol
 	//-------------------------------------------------------
 
 	/**
-	 * Read/Write multiple records for specified batch keys in one batch call.
-	 * This method allows different namespaces/bins for each key in the batch.
-	 * The returned records are located in the same list.
+	 * Read/write multiple records in one batch call; each item can be a different namespace/set/ops.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * java.util.List&lt;BatchRecord&gt; records = java.util.Arrays.asList(
+	 *   new BatchRead(new Key("ns", "set", "k1")),
+	 *   new BatchWrite(new Key("ns", "set", "k2"), new Bin("x", 1)));
+	 * boolean ok = client.operate(null, records);
+	 * client.close();
+	 * }</pre>
 	 * <p>
 	 * {@link BatchRecord} can be {@link BatchRead}, {@link BatchWrite}, {@link BatchDelete} or
-	 * {@link BatchUDF}.
-	 * <p>
-	 * Requires server version 6.0+
+	 * {@link BatchUDF}. Requires server version 6.0+.
 	 *
 	 * @param policy	batch configuration parameters, pass in null for defaults
-	 * @param records	list of unique record identifiers and read/write operations
+	 * @param records	list of batch record operations
 	 * @return			true if all batch sub-commands succeeded
-	 * @throws AerospikeException	if command fails
+	 * @throws AerospikeException	when command fails
+	 * @see BatchRead
+	 * @see BatchWrite
 	 */
 	public final boolean operate(BatchPolicy policy, List<BatchRecord> records)
 		throws AerospikeException {
@@ -3079,24 +3460,29 @@ public final boolean operate(BatchPolicy policy, List<BatchRecord> records)
 	}
 
 	/**
-	 * Asynchronously read/write multiple records for specified batch keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * This method allows different namespaces/bins to be requested for each key in the batch.
-	 * The returned records are located in the same list.
+	 * Asynchronously read/write multiple records in one batch; results in one callback.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * java.util.List&lt;BatchRecord&gt; records = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")));
+	 * client.operate(loop, new BatchOperateListListener() { ... }, null, records);
+	 * }</pre>
 	 * <p>
 	 * {@link BatchRecord} can be {@link BatchRead}, {@link BatchWrite}, {@link BatchDelete} or
-	 * {@link BatchUDF}.
-	 * <p>
-	 * Requires server version 6.0+
+	 * {@link BatchUDF}. Requires server version 6.0+.
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
-	 * @param records		list of unique record identifiers and read/write operations
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param records		list of batch record operations
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #operate(BatchPolicy, List)
+	 * @see BatchOperateListListener
 	 */
 	public final void operate(
 		EventLoop eventLoop,
@@ -3205,24 +3591,29 @@ public final void operate(
 	}
 
 	/**
-	 * Asynchronously read/write multiple records for specified batch keys in one batch call.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * This method allows different namespaces/bins to be requested for each key in the batch.
-	 * Each record result is returned in separate onRecord() calls.
+	 * Asynchronously read/write multiple records in one batch; each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * java.util.List&lt;BatchRecord&gt; records = java.util.Arrays.asList(new BatchRead(new Key("ns", "set", "k1")));
+	 * client.operate(loop, new BatchRecordSequenceListener() { ... }, null, records);
+	 * }</pre>
 	 * <p>
 	 * {@link BatchRecord} can be {@link BatchRead}, {@link BatchWrite}, {@link BatchDelete} or
-	 * {@link BatchUDF}.
-	 * <p>
-	 * Requires server version 6.0+
+	 * {@link BatchUDF}. Requires server version 6.0+.
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
 	 * @param listener		where to send results
 	 * @param policy		batch configuration parameters, pass in null for defaults
-	 * @param records		list of unique record identifiers and read/write operations
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param records		list of batch record operations
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #operate(BatchPolicy, List)
+	 * @see BatchRecordSequenceListener
 	 */
 	public final void operate(
 		EventLoop eventLoop,
@@ -3335,19 +3726,27 @@ public final void operate(
 	}
 
 	/**
-	 * Perform read/write operations on multiple keys. If a key is not found, the corresponding result
-	 * {@link BatchRecord#resultCode} will be {@link ResultCode#KEY_NOT_FOUND_ERROR}.
+	 * Perform the same read/write operations on multiple keys; result order matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * BatchResults results = client.operate(null, null, keys, Operation.get("bin1"));
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * Requires server version 6.0+
+	 * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
+	 * {@link ResultCode#KEY_NOT_FOUND_ERROR}. Use {@link Operation#get(String)} per bin; {@link Operation#get()} is not allowed.
+	 * Requires server version 6.0+.
 	 *
 	 * @param batchPolicy	batch configuration parameters, pass in null for defaults
 	 * @param writePolicy	write configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
-	 * @param ops
-	 * read/write operations to perform. {@link Operation#get()} is not allowed because it returns a
-	 * variable number of bins and makes it difficult (sometimes impossible) to lineup operations
-	 * with results. Instead, use {@link Operation#get(String)} for each bin name.
-	 * @throws AerospikeException.BatchRecordArray	which contains results for keys that did complete
+	 * @param ops			read/write operations to perform
+	 * @return				batch results (one per key)
+	 * @throws AerospikeException.BatchRecordArray	when some keys fail (contains partial results)
+	 * @see #operate(WritePolicy, Key, Operation...)
+	 * @see BatchResults
 	 */
 	public final BatchResults operate(
 		BatchPolicy batchPolicy,
@@ -3418,14 +3817,17 @@ public final BatchResults operate(
 	}
 
 	/**
-	 * Asynchronously perform read/write operations on multiple keys.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
-	 * {@link ResultCode#KEY_NOT_FOUND_ERROR}.
-	 * <p>
-	 * Requires server version 6.0+
+	 * Asynchronously perform the same read/write operations on multiple keys; results in one callback.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.operate(loop, new BatchRecordArrayListener() { ... }, null, null, keys, Operation.get("bin1"));
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -3433,11 +3835,10 @@ public final BatchResults operate(
 	 * @param batchPolicy	batch configuration parameters, pass in null for defaults
 	 * @param writePolicy	write configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
-	 * @param ops
-	 * read/write operations to perform. {@link Operation#get()} is not allowed because it returns a
-	 * variable number of bins and makes it difficult (sometimes impossible) to lineup operations
-	 * with results. Instead, use {@link Operation#get(String)} for each bin name.
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param ops			read/write operations (use Operation.get(String) per bin)
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #operate(BatchPolicy, BatchWritePolicy, Key[], Operation...)
+	 * @see BatchRecordArrayListener
 	 */
 	public final void operate(
 		EventLoop eventLoop,
@@ -3504,15 +3905,17 @@ public final void operate(
 	}
 
 	/**
-	 * Asynchronously perform read/write operations on multiple keys.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
-	 * If a key is not found, the corresponding result {@link BatchRecord#resultCode} will be
-	 * {@link ResultCode#KEY_NOT_FOUND_ERROR}.
-	 * <p>
-	 * Requires server version 6.0+
+	 * Asynchronously perform the same read/write operations on multiple keys; each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.operate(loop, new BatchRecordSequenceListener() { ... }, null, null, keys, Operation.get("bin1"));
+	 * }</pre>
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -3520,11 +3923,10 @@ public final void operate(
 	 * @param batchPolicy	batch configuration parameters, pass in null for defaults
 	 * @param writePolicy	write configuration parameters, pass in null for defaults
 	 * @param keys			array of unique record identifiers
-	 * @param ops
-	 * read/write operations to perform. {@link Operation#get()} is not allowed because it returns a
-	 * variable number of bins and makes it difficult (sometimes impossible) to lineup operations
-	 * with results. Instead, use {@link Operation#get(String)} for each bin name.
-	 * @throws AerospikeException	if event loop registration fails
+	 * @param ops			read/write operations (use Operation.get(String) per bin)
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #operate(BatchPolicy, BatchWritePolicy, Key[], Operation...)
+	 * @see BatchRecordSequenceListener
 	 */
 	public final void operate(
 		EventLoop eventLoop,
@@ -3783,16 +4185,23 @@ public final void scanPartitions(EventLoop eventLoop, RecordSequenceListener lis
 	//---------------------------------------------------------------
 
 	/**
-	 * Register package located in a file containing user defined functions with server.
-	 * This asynchronous server call will return before command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * RegisterTask instance.
+	 * Register a UDF package from a file with the server; returns a task to wait for completion.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * RegisterTask task = client.register(null, "myudf.lua", "myudf.lua", Language.LUA);
+	 * task.waitTillComplete(1000);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param clientPath			path of client file containing user defined functions, relative to current directory
-	 * @param serverPath			path to store user defined functions on the server, relative to configured script directory.
+	 * @param serverPath			path to store user defined functions on the server, relative to configured script directory
 	 * @param language				language of user defined functions
-	 * @throws AerospikeException	if register fails
+	 * @return						task to wait for completion
+	 * @throws AerospikeException	when register fails
+	 * @see RegisterTask
+	 * @see #execute(WritePolicy, Key, String, String, Value...)
 	 */
 	public final RegisterTask register(Policy policy, String clientPath, String serverPath, Language language)
 		throws AerospikeException {
@@ -3900,11 +4309,16 @@ public final void removeUdf(InfoPolicy policy, String serverPath)
 	}
 
 	/**
-	 * Execute user defined function on server and return results.
-	 * The function operates on a single record.
-	 * The package name is used to locate the udf file location:
+	 * Execute a UDF on a single record and return the result.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("ns", "set", "mykey");
+	 * Object result = client.execute(null, key, "myudf", "myFunc", Value.get("arg1"));
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * {@code udf file = <server udf dir>/<package name>.lua}
+	 * UDF file location: {@code <server udf dir>/<package name>.lua}
 	 *
 	 * @param policy				write configuration parameters, pass in null for defaults
 	 * @param key					unique record identifier
@@ -3912,7 +4326,9 @@ public final void removeUdf(InfoPolicy policy, String serverPath)
 	 * @param functionName			user defined function
 	 * @param functionArgs			arguments passed in to user defined function
 	 * @return						return value of user defined function
-	 * @throws AerospikeException	if command fails
+	 * @throws AerospikeException	when command fails
+	 * @see #register(Policy, String, String, Language)
+	 * @see #execute(EventLoop, ExecuteListener, WritePolicy, Key, String, String, Value...)
 	 */
 	public final Object execute(WritePolicy policy, Key key, String packageName, String functionName, Value... functionArgs)
 		throws AerospikeException {
@@ -3957,14 +4373,16 @@ public final Object execute(WritePolicy policy, Key key, String packageName, Str
 	}
 
 	/**
-	 * Asynchronously execute user defined function on server.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The function operates on a single record.
-	 * The package name is used to locate the udf file location:
-	 * <p>
-	 * {@code udf file = <server udf dir>/<package name>.lua}
+	 * Asynchronously execute a UDF on a single record.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.execute(loop, executeListener, null, key, "myudf", "myFunc", Value.get("arg1"));
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
@@ -3974,7 +4392,9 @@ public final Object execute(WritePolicy policy, Key key, String packageName, Str
 	 * @param packageName			server package name where user defined function resides
 	 * @param functionName			user defined function
 	 * @param functionArgs			arguments passed in to user defined function
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #execute(WritePolicy, Key, String, String, Value...)
+	 * @see ExecuteListener
 	 */
 	public final void execute(
 		EventLoop eventLoop,
@@ -4000,12 +4420,16 @@ public final void execute(
 	}
 
 	/**
-	 * Execute user defined function on server for each key and return results.
-	 * The package name is used to locate the udf file location:
-	 * <p>
-	 * {@code udf file = <server udf dir>/<package name>.lua}
+	 * Execute a UDF on each of the given keys and return batch results; result order matches key order.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * BatchResults results = client.execute(null, null, keys, "myudf", "myFunc", Value.get("arg1"));
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * Requires server version 6.0+
+	 * UDF file location: {@code <server udf dir>/<package name>.lua}. Requires server version 6.0+.
 	 *
 	 * @param batchPolicy	batch configuration parameters, pass in null for defaults
 	 * @param udfPolicy		udf configuration parameters, pass in null for defaults
@@ -4013,7 +4437,10 @@ public final void execute(
 	 * @param packageName	server package name where user defined function resides
 	 * @param functionName	user defined function
 	 * @param functionArgs	arguments passed in to user defined function
-	 * @throws AerospikeException.BatchRecordArray	which contains results for keys that did complete
+	 * @return				batch results (one per key)
+	 * @throws AerospikeException.BatchRecordArray	when some keys fail (contains partial results)
+	 * @see #execute(WritePolicy, Key, String, String, Value...)
+	 * @see BatchResults
 	 */
 	public final BatchResults execute(
 		BatchPolicy batchPolicy,
@@ -4082,15 +4509,19 @@ public final BatchResults execute(
 	}
 
 	/**
-	 * Asynchronously execute user defined function on server for each key and return results.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * The package name is used to locate the udf file location:
+	 * Asynchronously execute a UDF on each of the given keys; results in one callback.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.execute(loop, new BatchRecordArrayListener() { ... }, null, null, keys, "myudf", "myFunc", Value.get("arg1"));
+	 * }</pre>
 	 * <p>
-	 * {@code udf file = <server udf dir>/<package name>.lua}
-	 * <p>
-	 * Requires server version 6.0+
+	 * Requires server version 6.0+.
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -4101,7 +4532,9 @@ public final BatchResults execute(
 	 * @param packageName	server package name where user defined function resides
 	 * @param functionName	user defined function
 	 * @param functionArgs	arguments passed in to user defined function
-	 * @throws AerospikeException	if command fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #execute(BatchPolicy, BatchUDFPolicy, Key[], String, String, Value...)
+	 * @see BatchRecordArrayListener
 	 */
 	public final void execute(
 		EventLoop eventLoop,
@@ -4166,16 +4599,19 @@ public final void execute(
 	}
 
 	/**
-	 * Asynchronously execute user defined function on server for each key and return results.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * Each record result is returned in separate onRecord() calls.
-	 * <p>
-	 * The package name is used to locate the udf file location:
+	 * Asynchronously execute a UDF on each of the given keys; each result via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Key[] keys = new Key[] { new Key("ns", "set", "k1"), new Key("ns", "set", "k2") };
+	 * client.execute(loop, new BatchRecordSequenceListener() { ... }, null, null, keys, "myudf", "myFunc", Value.get("arg1"));
+	 * }</pre>
 	 * <p>
-	 * {@code udf file = <server udf dir>/<package name>.lua}
-	 * <p>
-	 * Requires server version 6.0+
+	 * Requires server version 6.0+.
 	 *
 	 * @param eventLoop		event loop that will process the command. If NULL, the event
 	 * 						loop will be chosen by round-robin.
@@ -4186,7 +4622,9 @@ public final void execute(
 	 * @param packageName	server package name where user defined function resides
 	 * @param functionName	user defined function
 	 * @param functionArgs	arguments passed in to user defined function
-	 * @throws AerospikeException	if command fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #execute(BatchPolicy, BatchUDFPolicy, Key[], String, String, Value...)
+	 * @see BatchRecordSequenceListener
 	 */
 	public final void execute(
 		EventLoop eventLoop,
@@ -4250,18 +4688,25 @@ public final void execute(
 	//----------------------------------------------------------
 
 	/**
-	 * Apply user defined function on records that match the background query statement filter.
-	 * Records are not returned to the client.
-	 * This asynchronous server call will return before the command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * ExecuteTask instance.
+	 * Run a UDF in the background on all records matching the statement; returns a task to wait for completion.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * ExecuteTask task = client.execute(null, stmt, "myudf", "myFunc", Value.get("arg1"));
+	 * task.waitTillComplete(5000);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				write configuration parameters, pass in null for defaults
 	 * @param statement				background query definition
 	 * @param packageName			server package where user defined function resides
 	 * @param functionName			function name
-	 * @param functionArgs			to pass to function name, if any
-	 * @throws AerospikeException	if command fails
+	 * @param functionArgs			arguments to pass to function, if any
+	 * @return						task to wait for completion
+	 * @throws AerospikeException	when command fails
+	 * @see ExecuteTask
+	 * @see #execute(WritePolicy, Statement, Operation...)
 	 */
 	public final ExecuteTask execute(
 		WritePolicy policy,
@@ -4293,16 +4738,23 @@ public final ExecuteTask execute(
 	}
 
 	/**
-	 * Apply operations on records that match the background query statement filter.
-	 * Records are not returned to the client.
-	 * This asynchronous server call will return before the command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * ExecuteTask instance.
+	 * Run operations in the background on all records matching the statement; returns a task to wait for completion.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * ExecuteTask task = client.execute(null, stmt, Operation.put(new Bin("flag", 1)));
+	 * task.waitTillComplete(5000);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				write configuration parameters, pass in null for defaults
 	 * @param statement				background query definition
-	 * @param operations			list of operations to be performed on selected records
-	 * @throws AerospikeException	if command fails
+	 * @param operations			operations to perform on selected records
+	 * @return						task to wait for completion
+	 * @throws AerospikeException	when command fails
+	 * @see ExecuteTask
+	 * @see #execute(WritePolicy, Statement, String, String, Value...)
 	 */
 	public final ExecuteTask execute(
 		WritePolicy policy,
@@ -4338,20 +4790,25 @@ public final ExecuteTask execute(
 	//--------------------------------------------------------
 
 	/**
-	 * Execute query on all server nodes and return record iterator. The query executor puts
-	 * records on a queue in separate threads. The calling thread concurrently pops records off
-	 * the queue through the record iterator.
+	 * Execute a query on all nodes and return a record iterator.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * RecordSet rs = client.query(null, stmt);
+	 * try { while (rs.next()) { Record r = rs.getRecord(); } } finally { rs.close(); }
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * This method is not recommended for paginated queries when the user does not iterate through
-	 * all records in the RecordSet. In this case, there is a lag between when the client marks the
-	 * last record retrieved from the server and when the record is retrieved from the RecordSet.
-	 * For this case, use {@link #query(QueryPolicy, Statement, QueryListener)} which uses a listener
-	 * callback (without a buffer) instead of a RecordSet.
+	 * For paginated use without consuming the full RecordSet, prefer {@link #query(QueryPolicy, Statement, QueryListener)}.
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
 	 * @return						record iterator
-	 * @throws AerospikeException	if query fails
+	 * @throws AerospikeException	when query fails
+	 * @see #query(EventLoop, RecordSequenceListener, QueryPolicy, Statement)
+	 * @see Statement
+	 * @see RecordSet
 	 */
 	public final RecordSet query(QueryPolicy policy, Statement statement)
 		throws AerospikeException {
@@ -4376,18 +4833,26 @@ public final RecordSet query(QueryPolicy policy, Statement statement)
 	}
 
 	/**
-	 * Asynchronously execute query on all server nodes.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
+	 * Asynchronously execute a query on all nodes; each record via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Statement stmt = new Statement("ns", "set");
+	 * client.query(loop, new RecordSequenceListener() { ... }, null, stmt);
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
 	 * @param listener				where to send results
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
-	 * @throws AerospikeException	if event loop registration fails
+	 * @throws AerospikeException	when event loop registration fails
+	 * @see #query(QueryPolicy, Statement)
+	 * @see RecordSequenceListener
 	 */
 	public final void query(EventLoop eventLoop, RecordSequenceListener listener, QueryPolicy policy, Statement statement)
 		throws AerospikeException {
@@ -4413,19 +4878,24 @@ public final void query(EventLoop eventLoop, RecordSequenceListener listener, Qu
 	}
 
 	/**
-	 * Execute query on all server nodes and return records via the listener. This method will
-	 * block until the query is complete. Listener callbacks are made within the scope of this call.
-	 * <p>
-	 * If {@link com.aerospike.client.policy.QueryPolicy#maxConcurrentNodes} is not 1, the supplied
-	 * listener must handle shared data in a thread-safe manner, because the listener will be called
-	 * by multiple query threads (one thread per node) in parallel.
+	 * Execute a query on all nodes and deliver records via the listener; blocks until complete.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * client.query(null, stmt, new QueryListener() { ... });
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * Requires server version 6.0+ if using a secondary index query.
+	 * If maxConcurrentNodes is not 1, the listener may be called from multiple threads.
+	 * Requires server version 6.0+ for secondary index queries.
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
 	 * @param listener				where to send results
-	 * @throws AerospikeException	if query fails
+	 * @throws AerospikeException	when query fails
+	 * @see #query(QueryPolicy, Statement)
+	 * @see QueryListener
 	 */
 	public final void query(
 		QueryPolicy policy,
@@ -4450,25 +4920,29 @@ public final void query(
 	}
 
 	/**
-	 * Execute query for specified partitions and return records via the listener. This method will
-	 * block until the query is complete. Listener callbacks are made within the scope of this call.
+	 * Execute a query for specified partitions and deliver records via the listener; blocks until complete.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * PartitionFilter filter = PartitionFilter.all();
+	 * client.query(null, stmt, filter, new QueryListener() { ... });
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * If {@link com.aerospike.client.policy.QueryPolicy#maxConcurrentNodes} is not 1, the supplied
-	 * listener must handle shared data in a thread-safe manner, because the listener will be called
-	 * by multiple query threads (one thread per node) in parallel.
-	 * <p>
-	 * The completion status of all partitions is stored in the partitionFilter when the query terminates.
-	 * This partitionFilter can then be used to resume an incomplete query at a later time.
-	 * This is the preferred method for query terminate/resume functionality.
-	 * <p>
-	 * Requires server version 6.0+ if using a secondary index query.
+	 * Completion status is stored in partitionFilter when the query ends; use it to resume later.
+	 * If maxConcurrentNodes is not 1, the listener may be called from multiple threads.
+	 * Requires server version 6.0+ for secondary index queries.
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
-	 * @param partitionFilter		data partition filter. Set to
-	 * 								{@link com.aerospike.client.query.PartitionFilter#all()} for all partitions.
+	 * @param partitionFilter		partition filter (e.g. {@link com.aerospike.client.query.PartitionFilter#all()}); updated on completion for resume
 	 * @param listener				where to send results
-	 * @throws AerospikeException	if query fails
+	 * @throws AerospikeException	when query fails
+	 * @see #queryPartitions(QueryPolicy, Statement, PartitionFilter)
+	 * @see #queryPartitions(EventLoop, RecordSequenceListener, QueryPolicy, Statement, PartitionFilter)
+	 * @see QueryListener
+	 * @see PartitionFilter
 	 */
 	public final void query(
 		QueryPolicy policy,
@@ -4494,15 +4968,26 @@ public final void query(
 	}
 
 	/**
-	 * Execute query on a single server node and return record iterator.  The query executor puts
-	 * records on a queue in a separate thread.  The calling thread concurrently pops records off
-	 * the queue through the record iterator.
+	 * Execute a query on a single node and return a record iterator.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * Node node = client.getNodes()[0];
+	 * RecordSet rs = client.queryNode(null, stmt, node);
+	 * try { while (rs.next()) { Record r = rs.getRecord(); } } finally { rs.close(); }
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
 	 * @param node					server node to execute query
 	 * @return						record iterator
-	 * @throws AerospikeException	if query fails
+	 * @throws AerospikeException	when query fails
+	 * @see #query(QueryPolicy, Statement)
+	 * @see #queryPartitions(QueryPolicy, Statement, PartitionFilter)
+	 * @see RecordSet
+	 * @see Node
 	 */
 	public final RecordSet queryNode(QueryPolicy policy, Statement statement, Node node)
 		throws AerospikeException {
@@ -4525,16 +5010,28 @@ public final RecordSet queryNode(QueryPolicy policy, Statement statement, Node n
 	}
 
 	/**
-	 * Execute query for specified partitions and return record iterator.  The query executor puts
-	 * records on a queue in separate threads.  The calling thread concurrently pops records off
-	 * the queue through the record iterator.
+	 * Execute a query for specified partitions and return a record iterator.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * PartitionFilter filter = PartitionFilter.all();
+	 * RecordSet rs = client.queryPartitions(null, stmt, filter);
+	 * try { while (rs.next()) { Record r = rs.getRecord(); } } finally { rs.close(); }
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * Requires server version 6.0+ if using a secondary index query.
+	 * Requires server version 6.0+ for secondary index queries.
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
-	 * @param partitionFilter		filter on a subset of data partitions
-	 * @throws AerospikeException	if query fails
+	 * @param partitionFilter		filter on a subset of data partitions (e.g. PartitionFilter.all())
+	 * @return						record iterator
+	 * @throws AerospikeException	when query fails
+	 * @see #query(QueryPolicy, Statement, PartitionFilter, QueryListener)
+	 * @see #queryPartitions(EventLoop, RecordSequenceListener, QueryPolicy, Statement, PartitionFilter)
+	 * @see PartitionFilter
+	 * @see RecordSet
 	 */
 	public final RecordSet queryPartitions(
 		QueryPolicy policy,
@@ -4560,21 +5057,32 @@ public final RecordSet queryPartitions(
 	}
 
 	/**
-	 * Asynchronously execute query for specified partitions.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
-	 * <p>
-	 * Each record result is returned in separate onRecord() calls.
+	 * Asynchronously execute a query for specified partitions; each record via onRecord().
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Statement stmt = new Statement("ns", "set");
+	 * PartitionFilter filter = PartitionFilter.all();
+	 * client.queryPartitions(loop, new RecordSequenceListener() { ... }, null, stmt, filter);
+	 * }</pre>
 	 * <p>
-	 * Requires server version 6.0+ if using a secondary index query.
+	 * Requires server version 6.0+ for secondary index queries.
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
 	 * @param listener				where to send results
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
-	 * @param partitionFilter		filter on a subset of data partitions
-	 * @throws AerospikeException	if query fails
+	 * @param partitionFilter		filter on a subset of data partitions (e.g. PartitionFilter.all())
+	 * @throws AerospikeException	when event loop registration fails or query fails
+	 * @see #queryPartitions(QueryPolicy, Statement, PartitionFilter)
+	 * @see #query(QueryPolicy, Statement, PartitionFilter, QueryListener)
+	 * @see RecordSequenceListener
+	 * @see PartitionFilter
 	 */
 	public final void queryPartitions(
 		EventLoop eventLoop,
@@ -4605,23 +5113,27 @@ public final void queryPartitions(
 	}
 
 	/**
-	 * Execute query, apply statement's aggregation function, and return result iterator. The query
-	 * executor puts results on a queue in separate threads.  The calling thread concurrently pops
-	 * results off the queue through the result iterator.
-	 * <p>
-	 * The aggregation function is called on both server and client (final reduce).  Therefore,
-	 * the Lua script files must also reside on both server and client.
-	 * The package name is used to locate the udf file location:
+	 * Execute a query with an aggregation UDF and return a result iterator; UDF is specified by package/function.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * ResultSet rs = client.queryAggregate(null, stmt, "myudf", "sum_single_bin", Value.get("bin1"));
+	 * try { while (rs.next()) { Object v = rs.getObject(); } } finally { rs.close(); }
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * {@code udf file = <udf dir>/<package name>.lua}
+	 * Aggregation runs on server and client (final reduce); UDF must exist on both. UDF file: {@code <udf dir>/<package name>.lua}
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
 	 * @param statement				query definition
-	 * @param packageName			server package where user defined function resides
+	 * @param packageName			server package where aggregation UDF resides
 	 * @param functionName			aggregation function name
-	 * @param functionArgs			arguments to pass to function name, if any
+	 * @param functionArgs			arguments to pass to function, if any
 	 * @return						result iterator
-	 * @throws AerospikeException	if query fails
+	 * @throws AerospikeException	when query fails
+	 * @see #queryAggregate(QueryPolicy, Statement)
+	 * @see ResultSet
 	 */
 	public final ResultSet queryAggregate(
 		QueryPolicy policy,
@@ -4635,18 +5147,26 @@ public final ResultSet queryAggregate(
 	}
 
 	/**
-	 * Execute query, apply statement's aggregation function, and return result iterator.
-	 * The aggregation function should be initialized via the statement's setAggregateFunction()
-	 * and should be located in a resource or a filesystem file.
+	 * Execute a query with the statement's aggregation function (set via setAggregateFunction()) and return result iterator.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * stmt.setAggregateFunction("myudf", "sum_single_bin", Value.get("bin1"));
+	 * ResultSet rs = client.queryAggregate(null, stmt);
+	 * try { while (rs.next()) { Object v = rs.getObject(); } } finally { rs.close(); }
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * The query executor puts results on a queue in separate threads.  The calling thread
-	 * concurrently pops results off the queue through the ResultSet iterator.
-	 * The aggregation function is called on both server and client (final reduce).
-	 * Therefore, the Lua script file must also reside on both server and client.
+	 * Aggregation runs on server and client (final reduce); UDF must exist on both.
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
-	 * @param statement				query definition
-	 * @throws AerospikeException	if query fails
+	 * @param statement				query definition (aggregation set via setAggregateFunction())
+	 * @return						result iterator
+	 * @throws AerospikeException	when query fails
+	 * @see #queryAggregate(QueryPolicy, Statement, String, String, Value...)
+	 * @see #queryAggregateNode(QueryPolicy, Statement, Node)
+	 * @see ResultSet
 	 */
 	public final ResultSet queryAggregate(QueryPolicy policy, Statement statement)
 		throws AerospikeException {
@@ -4662,20 +5182,28 @@ public final ResultSet queryAggregate(QueryPolicy policy, Statement statement)
 	}
 
 	/**
-	 * Execute query on a single server node, apply statement's aggregation function, and return
-	 * result iterator.
-	 * The aggregation function should be initialized via the statement's setAggregateFunction()
-	 * and should be located in a resource or a filesystem file.
+	 * Execute a query with aggregation on a single node; use statement's setAggregateFunction() first.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Statement stmt = new Statement("ns", "set");
+	 * stmt.setAggregateFunction("myudf", "sum_single_bin", Value.get("bin1"));
+	 * Node node = client.getNodes()[0];
+	 * ResultSet rs = client.queryAggregateNode(null, stmt, node);
+	 * try { while (rs.next()) { Object v = rs.getObject(); } } finally { rs.close(); }
+	 * client.close();
+	 * }</pre>
 	 * <p>
-	 * The query executor puts results on a queue in separate threads.  The calling thread
-	 * concurrently pops results off the queue through the ResultSet iterator.
-	 * The aggregation function is called on both server and client (final reduce).
-	 * Therefore, the Lua script file must also reside on both server and client.
+	 * Aggregation runs on server and client (final reduce); UDF must exist on both.
 	 *
 	 * @param policy				query configuration parameters, pass in null for defaults
-	 * @param statement				query definition
+	 * @param statement				query definition (aggregation set via setAggregateFunction())
 	 * @param node					server node to execute query
-	 * @throws AerospikeException	if query fails
+	 * @return						result iterator
+	 * @throws AerospikeException	when query fails
+	 * @see #queryAggregate(QueryPolicy, Statement)
+	 * @see ResultSet
+	 * @see Node
 	 */
 	public final ResultSet queryAggregateNode(QueryPolicy policy, Statement statement, Node node)
 		throws AerospikeException {
@@ -4694,10 +5222,14 @@ public final ResultSet queryAggregateNode(QueryPolicy policy, Statement statemen
 	//--------------------------------------------------------
 
 	/**
-	 * Create scalar secondary index.
-	 * This asynchronous server call will return before command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * IndexTask instance.
+	 * Create a scalar secondary index; returns a task to wait for completion.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * IndexTask task = client.createIndex(null, "ns", "set", "idx_bin1", "bin1", IndexType.STRING);
+	 * task.waitTillComplete(1000);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param namespace				namespace - equivalent to database name
@@ -4705,7 +5237,10 @@ public final ResultSet queryAggregateNode(QueryPolicy policy, Statement statemen
 	 * @param indexName				name of secondary index
 	 * @param binName				bin name that data is indexed on
 	 * @param indexType				underlying data type of secondary index
-	 * @throws AerospikeException	if index create fails
+	 * @return						task to wait for completion
+	 * @throws AerospikeException	when index create fails
+	 * @see IndexTask
+	 * @see #dropIndex(Policy, String, String, String)
 	 */
 	public final IndexTask createIndex(
 		Policy policy,
@@ -4719,10 +5254,14 @@ public final IndexTask createIndex(
 	}
 
 	/**
-	 * Create complex secondary index to be used on bins containing collections.
-	 * This asynchronous server call will return before command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * IndexTask instance.
+	 * Create a complex (CDT) secondary index on a collection bin; returns a task to wait for completion.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * IndexTask task = client.createIndex(null, "ns", "set", "idx_list", "bin1", IndexType.STRING, IndexCollectionType.LIST);
+	 * task.waitTillComplete(1000);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param namespace				namespace - equivalent to database name
@@ -4732,7 +5271,11 @@ public final IndexTask createIndex(
 	 * @param indexType				underlying data type of secondary index
 	 * @param indexCollectionType	index collection type
 	 * @param ctx					optional context to index on elements within a CDT
-	 * @throws AerospikeException	if index create fails
+	 * @return						task to wait for completion
+	 * @throws AerospikeException	when index create fails
+	 * @see #createIndex(Policy, String, String, String, String, IndexType)
+	 * @see IndexTask
+	 * @see IndexCollectionType
 	 */
 	public final IndexTask createIndex(
 		Policy policy,
@@ -4765,9 +5308,16 @@ public final IndexTask createIndex(
 	}
 
 	/**
-	 * Asynchronously create complex secondary index to be used on bins containing collections.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously create a complex (CDT) secondary index on a collection bin.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.createIndex(loop, new IndexListener() { ... }, null, "ns", "set", "idx_list", "bin1", IndexType.STRING, IndexCollectionType.LIST);
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
@@ -4780,7 +5330,9 @@ public final IndexTask createIndex(
 	 * @param indexType				underlying data type of secondary index
 	 * @param indexCollectionType	index collection type
 	 * @param ctx					optional context to index on elements within a CDT
-	 * @throws AerospikeException	if index create fails
+	 * @throws AerospikeException	when index create fails
+	 * @see #createIndex(Policy, String, String, String, String, IndexType, IndexCollectionType, CTX...)
+	 * @see IndexListener
 	 */
 	public final void createIndex(
 		EventLoop eventLoop,
@@ -4809,10 +5361,15 @@ public final void createIndex(
 	}
 
 	/**
-	 * Create an expression-based secondary index with the provided index collection type
-	 * This asynchronous server call will return before command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * IndexTask instance.
+	 * Create an expression-based secondary index; returns a task to wait for completion.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Expression exp = com.aerospike.client.exp.Exp.build(com.aerospike.client.exp.Exp.eq(com.aerospike.client.exp.Exp.stringBin("bin1"), com.aerospike.client.exp.Exp.val(1)));
+	 * IndexTask task = client.createIndex(null, "ns", "set", "idx_exp", IndexType.STRING, IndexCollectionType.DEFAULT, exp);
+	 * task.waitTillComplete(1000);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param namespace				namespace - equivalent to database name
@@ -4821,7 +5378,11 @@ public final void createIndex(
 	 * @param indexType				underlying data type of secondary index
 	 * @param indexCollectionType	index collection type
 	 * @param exp					expression on which to build the index
-	 * @throws AerospikeException
+	 * @return						task to wait for completion
+	 * @throws AerospikeException	when index create fails
+	 * @see #createIndex(Policy, String, String, String, String, IndexType)
+	 * @see Expression
+	 * @see IndexTask
 	 */
 	public final IndexTask createIndex(
 		Policy policy,
@@ -4853,10 +5414,17 @@ public final IndexTask createIndex(
 	}
 
 	/**
-	 * Asynchronously create an expression-based secondary index with the provided index collection type
-	 * This asynchronous server call will return before command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * IndexTask instance.
+	 * Asynchronously create an expression-based secondary index.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * Expression exp = com.aerospike.client.exp.Exp.build(com.aerospike.client.exp.Exp.eq(com.aerospike.client.exp.Exp.stringBin("bin1"), com.aerospike.client.exp.Exp.val(1)));
+	 * client.createIndex(loop, new IndexListener() { ... }, null, "ns", "set", "idx_exp", IndexType.STRING, IndexCollectionType.DEFAULT, exp);
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param namespace				namespace - equivalent to database name
@@ -4865,7 +5433,9 @@ public final IndexTask createIndex(
 	 * @param indexType				underlying data type of secondary index
 	 * @param indexCollectionType	index collection type
 	 * @param exp					expression on which to build the index
-	 * @throws AerospikeException
+	 * @throws AerospikeException	when index create fails
+	 * @see #createIndex(Policy, String, String, String, IndexType, IndexCollectionType, Expression)
+	 * @see IndexListener
 	 */
 	public final void createIndex(
 		EventLoop eventLoop,
@@ -4893,16 +5463,23 @@ public final void createIndex(
 	}
 
 	/**
-	 * Delete secondary index.
-	 * This asynchronous server call will return before command is complete.
-	 * The user can optionally wait for command completion by using the returned
-	 * IndexTask instance.
+	 * Delete a secondary index; returns a task to wait for completion.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * IndexTask task = client.dropIndex(null, "ns", "set", "idx_bin1");
+	 * task.waitTillComplete(1000);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				generic configuration parameters, pass in null for defaults
 	 * @param namespace				namespace - equivalent to database name
 	 * @param setName				optional set name - equivalent to database table
 	 * @param indexName				name of secondary index
-	 * @throws AerospikeException	if index drop fails
+	 * @return						task to wait for completion
+	 * @throws AerospikeException	when index drop fails
+	 * @see #createIndex(Policy, String, String, String, String, IndexType)
+	 * @see IndexTask
 	 */
 	public final IndexTask dropIndex(
 		Policy policy,
@@ -4930,9 +5507,16 @@ public final IndexTask dropIndex(
 	}
 
 	/**
-	 * Asynchronously delete secondary index.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously delete a secondary index.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.dropIndex(loop, new IndexListener() { ... }, null, "ns", "set", "idx_bin1");
+	 * }</pre>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
@@ -4941,7 +5525,9 @@ public final IndexTask dropIndex(
 	 * @param namespace				namespace - equivalent to database name
 	 * @param setName				optional set name - equivalent to database table
 	 * @param indexName				name of secondary index
-	 * @throws AerospikeException	if index drop fails
+	 * @throws AerospikeException	when index drop fails
+	 * @see #dropIndex(Policy, String, String, String)
+	 * @see IndexListener
 	 */
 	public final void dropIndex(
 		EventLoop eventLoop,
@@ -4970,22 +5556,29 @@ public final void dropIndex(
 	//-----------------------------------------------------------------
 
 	/**
-	 * Asynchronously make info commands.
-	 * This method registers the command with an event loop and returns.
-	 * The event loop thread will process the command and send the results to the listener.
+	 * Asynchronously send info command(s) to a node; results delivered to the listener.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * EventLoops eventLoops = new NioEventLoops(4);
+	 * ClientPolicy clientPolicy = new ClientPolicy();
+	 * clientPolicy.eventLoops = eventLoops;
+	 * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+	 * EventLoop loop = eventLoops.next();
+	 * client.info(loop, new InfoListener() { ... }, null, null, "build", "statistics");
+	 * }</pre>
 	 * <p>
-	 * The info protocol is a name/value pair based system, where an individual
-	 * database server node is queried to determine its configuration and status.
-	 * The list of supported info commands can be found at:
-	 * <a href="https://www.aerospike.com/docs/reference/info/index.html">https://www.aerospike.com/docs/reference/info/index.html</a>
+	 * Info is a name/value protocol for node configuration and status. Supported commands:
+	 * <a href="https://www.aerospike.com/docs/reference/info/index.html">aerospike.com/docs/reference/info</a>
 	 *
 	 * @param eventLoop				event loop that will process the command. If NULL, the event
 	 * 								loop will be chosen by round-robin.
 	 * @param listener				where to send results
 	 * @param policy				info configuration parameters, pass in null for defaults
 	 * @param node					server node to execute command, pass in null for random node
-	 * @param commands				list of info commands
-	 * @throws AerospikeException	if info commands fail
+	 * @param commands				list of info commands (e.g. "build", "statistics")
+	 * @throws AerospikeException	when info commands fail
+	 * @see Info
+	 * @see InfoListener
 	 */
 	public final void info(
 		EventLoop eventLoop,
@@ -5015,15 +5608,26 @@ public final void info(
 	//-----------------------------------------------------------------
 
 	/**
-	 * Set XDR filter for given datacenter name and namespace. The expression filter indicates
-	 * which records XDR should ship to the datacenter. If the expression filter is null, the
-	 * XDR filter will be removed.
+	 * Set or remove XDR filter for a datacenter and namespace; null filter removes the filter.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * // Filter: only replicate records where bin1 equals 1 (build expression via Exp, same as in filter policies)
+	 * Expression filter = com.aerospike.client.exp.Exp.build(
+	 *     com.aerospike.client.exp.Exp.eq(com.aerospike.client.exp.Exp.intBin("bin1"), com.aerospike.client.exp.Exp.val(1)));
+	 * client.setXDRFilter(null, "DC1", "ns", filter);
+	 * // Remove filter for the datacenter/namespace:
+	 * client.setXDRFilter(null, "DC1", "ns", null);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				info configuration parameters, pass in null for defaults
 	 * @param datacenter			XDR datacenter name
 	 * @param namespace				namespace - equivalent to database name
-	 * @param filter				expression filter
-	 * @throws AerospikeException	if command fails
+	 * @param filter				expression filter, or null to remove
+	 * @throws AerospikeException	when command fails
+	 * @see Expression
+	 * @see com.aerospike.client.exp.Exp
 	 */
 	public final void setXDRFilter(
 		InfoPolicy policy,
@@ -5054,14 +5658,21 @@ public final void setXDRFilter(
 	//-------------------------------------------------------
 
 	/**
-	 * Create user with password and roles.  Clear-text password will be hashed using bcrypt
-	 * before sending to server.
+	 * Create a user with password and roles; password is hashed (bcrypt) before sending.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.createUser(null, "newuser", "password", java.util.Arrays.asList("read-write"));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param user					user name
 	 * @param password				user password in clear-text format
-	 * @param roles					variable arguments array of role names.  Predefined roles are listed in {@link com.aerospike.client.admin.Role}
-	 * @throws AerospikeException	if command fails
+	 * @param roles					list of role names; see {@link com.aerospike.client.admin.Role}
+	 * @throws AerospikeException	when command fails
+	 * @see #dropUser(AdminPolicy, String)
+	 * @see #queryUser(AdminPolicy, String)
 	 */
 	public final void createUser(AdminPolicy policy, String user, String password, List<String> roles)
 		throws AerospikeException {
@@ -5071,13 +5682,20 @@ public final void createUser(AdminPolicy policy, String user, String password, L
 	}
 
 	/**
-	 * Create PKI user with roles.  PKI users are authenticated via TLS and a certificate instead of a password.
-	 * WARNING: This function should only be called for server versions 8.1+
+	 * Create a PKI user with roles (TLS/certificate auth). Server 8.1+ only.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.createPkiUser(null, "pkiuser", java.util.Arrays.asList("read-write"));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param user					user name
-	 * @param roles					variable arguments array of role names.  Predefined roles are listed in {@link com.aerospike.client.admin.Role}
-	 * @throws AerospikeException	if command fails
+	 * @param roles					list of role names; see {@link com.aerospike.client.admin.Role}
+	 * @throws AerospikeException	when command fails
+	 * @see #createUser(AdminPolicy, String, String, List)
+	 * @see #dropUser(AdminPolicy, String)
 	 */
 	public final void createPkiUser(AdminPolicy policy, String user, List<String> roles)
 		throws AerospikeException {
@@ -5086,11 +5704,19 @@ public final void createPkiUser(AdminPolicy policy, String user, List<String> ro
 	}
 
 	/**
-	 * Remove user from cluster.
+	 * Remove a user from the cluster.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.dropUser(null, "olduser");
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param user					user name
-	 * @throws AerospikeException	if command fails
+	 * @throws AerospikeException	when command fails
+	 * @see #createUser(AdminPolicy, String, String, List)
+	 * @see #queryUser(AdminPolicy, String)
 	 */
 	public final void dropUser(AdminPolicy policy, String user)
 		throws AerospikeException {
@@ -5099,12 +5725,19 @@ public final void dropUser(AdminPolicy policy, String user)
 	}
 
 	/**
-	 * Change user's password.
+	 * Change a user's password (caller or another user if admin).
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.changePassword(null, "myuser", "newpassword");
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param user					user name
-	 * @param password				user password in clear-text format
-	 * @throws AerospikeException	if command fails
+	 * @param password				new password in clear-text format
+	 * @throws AerospikeException	when command fails
+	 * @see #createUser(AdminPolicy, String, String, List)
 	 */
 	public final void changePassword(AdminPolicy policy, String user, String password)
 		throws AerospikeException {
@@ -5132,12 +5765,20 @@ public final void changePassword(AdminPolicy policy, String user, String passwor
 	}
 
 	/**
-	 * Add roles to user's list of roles.
+	 * Add roles to a user's list of roles.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.grantRoles(null, "myuser", java.util.Arrays.asList("read-write", "user-admin"));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param user					user name
-	 * @param roles					role names.  Predefined roles are listed in {@link com.aerospike.client.admin.Role}
-	 * @throws AerospikeException	if command fails
+	 * @param roles					role names; see {@link com.aerospike.client.admin.Role}
+	 * @throws AerospikeException	when command fails
+	 * @see #revokeRoles(AdminPolicy, String, List)
+	 * @see #queryUser(AdminPolicy, String)
 	 */
 	public final void grantRoles(AdminPolicy policy, String user, List<String> roles)
 		throws AerospikeException {
@@ -5146,12 +5787,20 @@ public final void grantRoles(AdminPolicy policy, String user, List<String> roles
 	}
 
 	/**
-	 * Remove roles from user's list of roles.
+	 * Remove roles from a user's list of roles.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.revokeRoles(null, "myuser", java.util.Arrays.asList("user-admin"));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param user					user name
-	 * @param roles					role names.  Predefined roles are listed in {@link com.aerospike.client.admin.Role}
-	 * @throws AerospikeException	if command fails
+	 * @param roles					role names to remove; see {@link com.aerospike.client.admin.Role}
+	 * @throws AerospikeException	when command fails
+	 * @see #grantRoles(AdminPolicy, String, List)
+	 * @see #queryUser(AdminPolicy, String)
 	 */
 	public final void revokeRoles(AdminPolicy policy, String user, List<String> roles)
 		throws AerospikeException {
@@ -5160,12 +5809,24 @@ public final void revokeRoles(AdminPolicy policy, String user, List<String> role
 	}
 
 	/**
-	 * Create user defined role.
+	 * Create a user-defined role with the given privileges.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Privilege p = new Privilege();
+	 * p.code = PrivilegeCode.READ_WRITE;
+	 * p.namespace = "ns";
+	 * client.createRole(null, "myrole", java.util.Collections.singletonList(p));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @param privileges			privileges assigned to the role.
-	 * @throws AerospikeException	if command fails
+	 * @param privileges			privileges assigned to the role
+	 * @throws AerospikeException	when command fails
+	 * @see #dropRole(AdminPolicy, String)
+	 * @see #queryRole(AdminPolicy, String)
+	 * @see Privilege
 	 */
 	public final void createRole(AdminPolicy policy, String roleName, List<Privilege> privileges)
 		throws AerospikeException {
@@ -5174,14 +5835,24 @@ public final void createRole(AdminPolicy policy, String roleName, List<Privilege
 	}
 
 	/**
-	 * Create user defined role with optional privileges and whitelist.
+	 * Create a user-defined role with optional privileges and IP whitelist.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Privilege p = new Privilege();
+	 * p.code = PrivilegeCode.READ_WRITE;
+	 * p.namespace = "ns";
+	 * client.createRole(null, "myrole", java.util.Collections.singletonList(p), java.util.Arrays.asList("10.1.2.0/24"));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @param privileges			optional list of privileges assigned to role.
-	 * @param whitelist				optional list of allowable IP addresses assigned to role.
-	 * 								IP addresses can contain wildcards (ie. 10.1.2.0/24).
-	 * @throws AerospikeException	if command fails
+	 * @param privileges			optional list of privileges assigned to role
+	 * @param whitelist				optional list of allowable IP addresses (e.g. 10.1.2.0/24)
+	 * @throws AerospikeException	when command fails
+	 * @see #createRole(AdminPolicy, String, List)
+	 * @see #setWhitelist(AdminPolicy, String, List)
 	 */
 	public final void createRole(AdminPolicy policy, String roleName, List<Privilege> privileges, List<String> whitelist)
 		throws AerospikeException {
@@ -5190,17 +5861,28 @@ public final void createRole(AdminPolicy policy, String roleName, List<Privilege
 	}
 
 	/**
-	 * Create user defined role with optional privileges, whitelist and read/write quotas.
-	 * Quotas require server security configuration "enable-quotas" to be set to true.
+	 * Create a user-defined role with optional privileges, whitelist, and read/write quotas.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Privilege p = new Privilege();
+	 * p.code = PrivilegeCode.READ_WRITE;
+	 * p.namespace = "ns";
+	 * client.createRole(null, "myrole", java.util.Collections.singletonList(p), java.util.Arrays.asList("10.1.2.0/24"), 1000, 500);
+	 * client.close();
+	 * }</pre>
+	 * <p>
+	 * Quotas require server "enable-quotas" to be true.
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @param privileges			optional list of privileges assigned to role.
-	 * @param whitelist				optional list of allowable IP addresses assigned to role.
-	 * 								IP addresses can contain wildcards (ie. 10.1.2.0/24).
-	 * @param readQuota				optional maximum reads per second limit, pass in zero for no limit.
-	 * @param writeQuota			optional maximum writes per second limit, pass in zero for no limit.
-	 * @throws AerospikeException	if command fails
+	 * @param privileges			optional list of privileges assigned to role
+	 * @param whitelist				optional list of allowable IP addresses (e.g. 10.1.2.0/24)
+	 * @param readQuota				maximum reads per second, or zero for no limit
+	 * @param writeQuota			maximum writes per second, or zero for no limit
+	 * @throws AerospikeException	when command fails
+	 * @see #createRole(AdminPolicy, String, List, List)
+	 * @see #setQuotas(AdminPolicy, String, int, int)
 	 */
 	public final void createRole(
 		AdminPolicy policy,
@@ -5215,11 +5897,19 @@ public final void createRole(
 	}
 
 	/**
-	 * Drop user defined role.
+	 * Drop a user-defined role.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.dropRole(null, "myrole");
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @throws AerospikeException	if command fails
+	 * @throws AerospikeException	when command fails
+	 * @see #createRole(AdminPolicy, String, List)
+	 * @see #queryRole(AdminPolicy, String)
 	 */
 	public final void dropRole(AdminPolicy policy, String roleName)
 		throws AerospikeException {
@@ -5228,12 +5918,24 @@ public final void dropRole(AdminPolicy policy, String roleName)
 	}
 
 	/**
-	 * Grant privileges to an user defined role.
+	 * Grant privileges to a user-defined role.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Privilege p = new Privilege();
+	 * p.code = PrivilegeCode.DATA_ADMIN;
+	 * p.namespace = "ns";
+	 * client.grantPrivileges(null, "myrole", java.util.Collections.singletonList(p));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @param privileges			privileges assigned to the role.
-	 * @throws AerospikeException	if command fails
+	 * @param privileges			privileges to add to the role
+	 * @throws AerospikeException	when command fails
+	 * @see #revokePrivileges(AdminPolicy, String, List)
+	 * @see #queryRole(AdminPolicy, String)
+	 * @see Privilege
 	 */
 	public final void grantPrivileges(AdminPolicy policy, String roleName, List<Privilege> privileges)
 		throws AerospikeException {
@@ -5242,12 +5944,24 @@ public final void grantPrivileges(AdminPolicy policy, String roleName, List<Priv
 	}
 
 	/**
-	 * Revoke privileges from an user defined role.
+	 * Revoke privileges from a user-defined role.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Privilege p = new Privilege();
+	 * p.code = PrivilegeCode.DATA_ADMIN;
+	 * p.namespace = "ns";
+	 * client.revokePrivileges(null, "myrole", java.util.Collections.singletonList(p));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @param privileges			privileges assigned to the role.
-	 * @throws AerospikeException	if command fails
+	 * @param privileges			privileges to remove from the role
+	 * @throws AerospikeException	when command fails
+	 * @see #grantPrivileges(AdminPolicy, String, List)
+	 * @see #queryRole(AdminPolicy, String)
+	 * @see Privilege
 	 */
 	public final void revokePrivileges(AdminPolicy policy, String roleName, List<Privilege> privileges)
 		throws AerospikeException {
@@ -5256,13 +5970,20 @@ public final void revokePrivileges(AdminPolicy policy, String roleName, List<Pri
 	}
 
 	/**
-	 * Set IP address whitelist for a role.  If whitelist is null or empty, remove existing whitelist from role.
+	 * Set or remove IP whitelist for a role; null or empty removes the existing whitelist.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.setWhitelist(null, "myrole", java.util.Arrays.asList("10.1.2.0/24", "192.168.1.0/24"));
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @param whitelist				list of allowable IP addresses or null.
-	 * 								IP addresses can contain wildcards (ie. 10.1.2.0/24).
-	 * @throws AerospikeException	if command fails
+	 * @param whitelist				list of allowable IP addresses (e.g. 10.1.2.0/24), or null to remove
+	 * @throws AerospikeException	when command fails
+	 * @see #createRole(AdminPolicy, String, List, List)
+	 * @see #queryRole(AdminPolicy, String)
 	 */
 	public final void setWhitelist(AdminPolicy policy, String roleName, List<String> whitelist)
 		throws AerospikeException {
@@ -5271,14 +5992,21 @@ public final void setWhitelist(AdminPolicy policy, String roleName, List<String>
 	}
 
 	/**
-	 * Set maximum reads/writes per second limits for a role.  If a quota is zero, the limit is removed.
-	 * Quotas require server security configuration "enable-quotas" to be set to true.
+	 * Set read/write quotas for a role; zero removes the limit. Requires server "enable-quotas".
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.setQuotas(null, "myrole", 1000, 500);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
 	 * @param roleName				role name
-	 * @param readQuota				maximum reads per second limit, pass in zero for no limit.
-	 * @param writeQuota			maximum writes per second limit, pass in zero for no limit.
-	 * @throws AerospikeException	if command fails
+	 * @param readQuota				maximum reads per second, or zero for no limit
+	 * @param writeQuota			maximum writes per second, or zero for no limit
+	 * @throws AerospikeException	when command fails
+	 * @see #createRole(AdminPolicy, String, List, List, int, int)
+	 * @see #queryRole(AdminPolicy, String)
 	 */
 	public final void setQuotas(AdminPolicy policy, String roleName, int readQuota, int writeQuota)
 		throws AerospikeException {
@@ -5287,11 +6015,21 @@ public final void setQuotas(AdminPolicy policy, String roleName, int readQuota,
 	}
 
 	/**
-	 * Retrieve roles for a given user.
+	 * Retrieve a single user and their roles.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * User u = client.queryUser(null, "myuser");
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
-	 * @param user					user name filter
-	 * @throws AerospikeException	if command fails
+	 * @param user					user name
+	 * @return						user with roles, or null if not found
+	 * @throws AerospikeException	when command fails
+	 * @see #queryUsers(AdminPolicy)
+	 * @see #createUser(AdminPolicy, String, String, List)
+	 * @see User
 	 */
 	public final User queryUser(AdminPolicy policy, String user)
 		throws AerospikeException {
@@ -5301,9 +6039,18 @@ public final User queryUser(AdminPolicy policy, String user)
 
 	/**
 	 * Retrieve all users and their roles.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * java.util.List&lt;User&gt; users = client.queryUsers(null);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
-	 * @throws AerospikeException	if command fails
+	 * @return						list of users with roles
+	 * @throws AerospikeException	when command fails
+	 * @see #queryUser(AdminPolicy, String)
+	 * @see User
 	 */
 	public final List<User> queryUsers(AdminPolicy policy)
 		throws AerospikeException {
@@ -5312,11 +6059,21 @@ public final List<User> queryUsers(AdminPolicy policy)
 	}
 
 	/**
-	 * Retrieve role definition.
+	 * Retrieve a single role definition (privileges, whitelist, quotas).
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Role r = client.queryRole(null, "myrole");
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
-	 * @param roleName				role name filter
-	 * @throws AerospikeException	if command fails
+	 * @param roleName				role name
+	 * @return						role definition, or null if not found
+	 * @throws AerospikeException	when command fails
+	 * @see #queryRoles(AdminPolicy)
+	 * @see #createRole(AdminPolicy, String, List)
+	 * @see Role
 	 */
 	public final Role queryRole(AdminPolicy policy, String roleName)
 		throws AerospikeException {
@@ -5325,10 +6082,19 @@ public final Role queryRole(AdminPolicy policy, String roleName)
 	}
 
 	/**
-	 * Retrieve all roles.
+	 * Retrieve all role definitions.
+	 * <p>Example usage for this method.</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * java.util.List&lt;Role&gt; roles = client.queryRoles(null);
+	 * client.close();
+	 * }</pre>
 	 *
 	 * @param policy				admin configuration parameters, pass in null for defaults
-	 * @throws AerospikeException	if command fails
+	 * @return						list of roles
+	 * @throws AerospikeException	when command fails
+	 * @see #queryRole(AdminPolicy, String)
+	 * @see Role
 	 */
 	public final List<Role> queryRoles(AdminPolicy policy)
 		throws AerospikeException {
diff --git a/client/src/com/aerospike/client/AerospikeException.java b/client/src/com/aerospike/client/AerospikeException.java
index 8d356593c..de8d71979 100644
--- a/client/src/com/aerospike/client/AerospikeException.java
+++ b/client/src/com/aerospike/client/AerospikeException.java
@@ -23,7 +23,37 @@
 import java.util.List;
 
 /**
- * Aerospike exceptions that can be thrown from the client.
+ * Base exception for client errors; holds result code, node, policy, optional sub-exceptions, and in-doubt flag.
+ * <p>
+ * Use {@link #getResultCode()} and {@link ResultCode#getResultString(int)} to interpret; use {@link #getBaseMessage()} for the message without metadata. Subclasses denote timeout, connection, batch, transaction commit, and scan/query termination.
+ *
+ * <p><b>Example:</b>
+ * <p>Catch an exception, get result code and message, and check in-doubt for writes.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *  client.put(null, key, bins);
+ * } catch (AerospikeException e) {
+ *   int code = e.getResultCode();
+ *   String msg = ResultCode.getResultString(code);
+ *   if (e.getInDoubt()) {
+ *     // write may have completed
+ *   }
+ * }
+ * }</pre>
+ *
+ * @see ResultCode
+ * @see #getResultCode
+ * @see #getBaseMessage
+ * @see #keepConnection()
+ * @see Timeout
+ * @see Connection
+ * @see InvalidNode
+ * @see BatchRecords
+ * @see BatchRecordArray
+ * @see Commit
+ * @see ScanTerminated
+ * @see QueryTerminated
  */
 public class AerospikeException extends RuntimeException {
 	private static final long serialVersionUID = 1L;
@@ -121,7 +151,9 @@ public String getMessage() {
 	}
 
 	/**
-	 * Return base message without extra metadata.
+	 * Return base message without extra metadata (result code, node, policy, inDoubt).
+	 *
+	 * @return the underlying message or the result code string if null
 	 */
 	public String getBaseMessage() {
 		String message = super.getMessage();
@@ -129,7 +161,9 @@ public String getBaseMessage() {
 	}
 
 	/**
-	 * Should connection be put back into pool.
+	 * Whether the connection should be returned to the pool after this exception.
+	 *
+	 * @return true if the connection is reusable
 	 */
 	public final boolean keepConnection() {
 		return ResultCode.keepConnection(resultCode);
@@ -224,7 +258,12 @@ public void setInDoubt(boolean inDoubt) {
 	}
 
 	/**
-	 * Exception thrown when database request expires before completing.
+	 * Thrown when a database request expires before completing (client or server timeout).
+	 * <p>
+	 * Fields {@link #connectTimeout}, {@link #socketTimeout}, {@link #timeout} reflect policy values; {@link #client} is true for client-initiated timeout.
+	 *
+	 * @see ResultCode#TIMEOUT
+	 * @see com.aerospike.client.policy.Policy#totalTimeout
 	 */
 	public static final class Timeout extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -310,7 +349,9 @@ public Timeout(Node node, int connectTimeout, int socketTimeout, int totalTimeou
 	}
 
 	/**
-	 * Exception thrown when a Java serialization error occurs.
+	 * Thrown when a Java serialization error occurs (e.g. value cannot be serialized for the wire).
+	 *
+	 * @see ResultCode#SERIALIZE_ERROR
 	 */
 	public static final class Serialize extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -325,7 +366,9 @@ public Serialize(String message) {
 	}
 
 	/**
-	 * Exception thrown when client can't parse data returned from server.
+	 * Thrown when the client cannot parse data returned from the server.
+	 *
+	 * @see ResultCode#PARSE_ERROR
 	 */
 	public static final class Parse extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -336,7 +379,9 @@ public Parse(String message) {
 	}
 
 	/**
-	 * Exception thrown when client can't connect to the server.
+	 * Thrown when the client cannot connect to the server (e.g. host unreachable, connection refused).
+	 *
+	 * @see ResultCode#SERVER_NOT_AVAILABLE
 	 */
 	public static final class Connection extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -359,8 +404,9 @@ public Connection(int resultCode, String message) {
 	}
 
 	/**
-	 * Exception thrown when the selected node is not active, or when the namespace 
-	 * is removed after the client has connected.
+	 * Thrown when the selected node is not active or the namespace is removed after the client has connected.
+	 *
+	 * @see ResultCode#INVALID_NODE_ERROR
 	 */
 	public static final class InvalidNode extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -380,7 +426,9 @@ public InvalidNode(String message) {
 	}
 
 	/**
-	 * Exception thrown when namespace is invalid.
+	 * Thrown when the namespace is invalid or not found in the partition map.
+	 *
+	 * @see ResultCode#INVALID_NAMESPACE
 	 */
 	public static final class InvalidNamespace extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -392,11 +440,14 @@ public InvalidNamespace(String ns, int mapSize) {
 	}
 
 	/**
-	 * Exception thrown when a batch exists method fails.
+	 * Thrown when a batch exists method fails; {@link #exists} holds per-key existence results for keys that were completed.
+	 *
+	 * @see com.aerospike.client.AerospikeClient#exists(BatchPolicy, Key[])
 	 */
 	public static final class BatchExists extends AerospikeException {
 		private static final long serialVersionUID = 1L;
 
+		/** Existence result per key; length matches the request key array. */
 		public final boolean[] exists;
 
 		public BatchExists(boolean[] exists, Throwable e) {
@@ -406,13 +457,14 @@ public BatchExists(boolean[] exists, Throwable e) {
 	}
 
 	/**
-	 * Exception thrown when a batch read method fails.
-	 * The records fields contains responses for key requests that succeeded and null
-	 * records for key requests that failed.
+	 * Thrown when a batch read method fails; {@link #records} contains responses for keys that succeeded (null for failed keys).
+	 *
+	 * @see com.aerospike.client.AerospikeClient#get
 	 */
 	public static final class BatchRecords extends AerospikeException {
 		private static final long serialVersionUID = 1L;
 
+		/** Record per key; null for keys that failed or were not found. */
 		public final Record[] records;
 
 		public BatchRecords(Record[] records, Throwable e) {
@@ -422,13 +474,16 @@ public BatchRecords(Record[] records, Throwable e) {
 	}
 
 	/**
-	 * Exception thrown when a batch write method fails.
-	 * The records fields contains responses for key requests that succeeded
-	 * and resultCodes for key requests that failed.
+	 * Thrown when a batch write/operate/delete method fails; {@link #records} contains per-key results (use {@link BatchRecord#resultCode} for each).
+	 *
+	 * @see BatchRecord
+	 * @see com.aerospike.client.AerospikeClient#operate
+	 * @see com.aerospike.client.AerospikeClient#delete
 	 */
 	public static final class BatchRecordArray extends AerospikeException {
 		private static final long serialVersionUID = 1L;
 
+		/** BatchRecord per key; check each resultCode. */
 		public final BatchRecord[] records;
 
 		public BatchRecordArray(BatchRecord[] records, Throwable e) {
@@ -443,7 +498,10 @@ public BatchRecordArray(BatchRecord[] records, String message, Throwable e) {
 	}
 
 	/**
-	 * Exception thrown when scan was terminated prematurely.
+	 * Thrown when a scan is terminated prematurely (e.g. by the user throwing from {@link com.aerospike.client.ScanCallback}).
+	 *
+	 * @see ResultCode#SCAN_TERMINATED
+	 * @see com.aerospike.client.ScanCallback
 	 */
 	public static final class ScanTerminated extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -458,7 +516,10 @@ public ScanTerminated(Throwable e) {
 	}
 
 	/**
-	 * Exception thrown when query was terminated prematurely.
+	 * Thrown when a query is terminated prematurely (e.g. by the user throwing from {@link com.aerospike.client.query.QueryListener}).
+	 *
+	 * @see ResultCode#QUERY_TERMINATED
+	 * @see com.aerospike.client.query.QueryListener
 	 */
 	public static final class QueryTerminated extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -473,8 +534,10 @@ public QueryTerminated(Throwable e) {
 	}
 
 	/**
-	 * Exception thrown when async command was rejected because the
-	 * async delay queue is full.
+	 * Thrown when an async command was rejected because the async delay queue is full.
+	 *
+	 * @see ResultCode#ASYNC_QUEUE_FULL
+	 * @see Backoff
 	 */
 	public static final class AsyncQueueFull extends Backoff {
 		private static final long serialVersionUID = 1L;
@@ -485,8 +548,9 @@ public AsyncQueueFull() {
 	}
 
 	/**
-	 * Exception thrown when node is in backoff mode due to excessive
-	 * number of errors.
+	 * Thrown when a node is in backoff mode due to an excessive number of errors.
+	 *
+	 * @see AsyncQueueFull
 	 */
 	public static class Backoff extends AerospikeException {
 		private static final long serialVersionUID = 1L;
@@ -497,26 +561,36 @@ public Backoff(int resultCode) {
 	}
 
 	/**
-	 * Exception thrown when a transaction commit fails.
+	 * Thrown when a transaction commit fails; use {@link #error} for the commit error code and {@link #verifyRecords}/{@link #rollRecords} for per-key details.
+	 * <p>
+	 * Catch when calling {@link com.aerospike.client.AerospikeClient#commit}; then call {@link com.aerospike.client.AerospikeClient#abort} if appropriate.
+	 *
+	 * <p><b>Example:</b>
+	 * <p>Catch commit failure, read error and abort the transaction.</p>
+	 * <pre>{@code
+	 * try {
+	 *   client.commit(txn);
+	 * } catch (AerospikeException.Commit e) {
+	 *   CommitError err = e.error;
+	 *   client.abort(txn);
+	 * }
+	 * }</pre>
+	 *
+	 * @see CommitError
+	 * @see CommitStatus
+	 * @see com.aerospike.client.AerospikeClient#commit
+	 * @see com.aerospike.client.AerospikeClient#abort
 	 */
 	public static final class Commit extends AerospikeException {
 		private static final long serialVersionUID = 1L;
 
-		/**
-		 * Error status of the attempted commit.
-		 */
+		/** Error status of the attempted commit. */
 		public final CommitError error;
 
-		/**
-		 * Verify result for each read key in the transaction. May be null if failure occurred
-		 * before verify.
-		 */
+		/** Verify result per read key; null if failure occurred before verify. */
 		public final BatchRecord[] verifyRecords;
 
-		/**
-		 * Roll forward/backward result for each write key in the transaction. May be null if
-		 * failure occurred before roll forward/backward.
-		 */
+		/** Roll forward/backward result per write key; null if failure occurred before roll. */
 		public final BatchRecord[] rollRecords;
 
 		public Commit(CommitError error, BatchRecord[] verifyRecords, BatchRecord[] rollRecords) {
diff --git a/client/src/com/aerospike/client/BatchDelete.java b/client/src/com/aerospike/client/BatchDelete.java
index 931babd94..c29a04ed9 100644
--- a/client/src/com/aerospike/client/BatchDelete.java
+++ b/client/src/com/aerospike/client/BatchDelete.java
@@ -23,7 +23,25 @@
 import com.aerospike.client.policy.Policy;
 
 /**
- * Batch delete operation.
+ * Batch delete item: one key to delete; optional {@link com.aerospike.client.policy.BatchDeletePolicy}.
+ * <p>
+ * Pass a list to {@link com.aerospike.client.AerospikeClient#operate} (BatchRecord list can mix BatchDelete with other types) or use {@link com.aerospike.client.AerospikeClient#delete(BatchPolicy, BatchDeletePolicy, Key[])} for keys-only with a single policy. After the call, check {@link BatchRecord#resultCode}.
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchDelete[] deletes = new BatchDelete[] {
+ *   new BatchDelete(new Key("ns", "set", "k1")),
+ *   new BatchDelete(new BatchDeletePolicy(), new Key("ns", "set", "k2"))
+ * };
+ * client.operate(null, java.util.Arrays.asList(deletes));
+ * for (BatchDelete bd : deletes) {
+ *   int rc = bd.resultCode;
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.AerospikeClient#delete
  */
 public final class BatchDelete extends BatchRecord {
 	/**
diff --git a/client/src/com/aerospike/client/BatchRead.java b/client/src/com/aerospike/client/BatchRead.java
index c9454171f..7320585cf 100644
--- a/client/src/com/aerospike/client/BatchRead.java
+++ b/client/src/com/aerospike/client/BatchRead.java
@@ -23,8 +23,27 @@
 import com.aerospike.client.policy.Policy;
 
 /**
- * Batch key and read only operations with default policy.
- * Used in batch read commands where different bins are needed for each key.
+ * Batch get item: one key with optional bin names, read-all-bins flag, or {@link Operation} list (variable bins per key).
+ * <p>
+ * Use when each key needs different bins or operations. Pass an array to {@link com.aerospike.client.AerospikeClient#get(BatchPolicy, BatchRead[])} or async overloads with {@link com.aerospike.client.listener.BatchListListener} / {@link com.aerospike.client.listener.BatchSequenceListener}. Use {@link Operation#get(String)} per bin, not {@link Operation#get()}.
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchRead[] batchReads = new BatchRead[] {
+ *   new BatchRead(new Key("ns", "set", "k1"), new String[] { "a", "b" }),
+ *   new BatchRead(new Key("ns", "set", "k2"), true),
+ *   new BatchRead(new Key("ns", "set", "k3"), new Operation[] { Operation.get("x"), Operation.get("y") })
+ * };
+ * client.get(null, batchReads);
+ * for (BatchRead br : batchReads) {
+ *   if (br.record != null) { Record r = br.record; }
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.listener.BatchListListener
+ * @see com.aerospike.client.listener.BatchSequenceListener
  */
 public final class BatchRead extends BatchRecord {
 	/**
diff --git a/client/src/com/aerospike/client/BatchRecord.java b/client/src/com/aerospike/client/BatchRecord.java
index 7a1b32ca6..58c285f66 100644
--- a/client/src/com/aerospike/client/BatchRecord.java
+++ b/client/src/com/aerospike/client/BatchRecord.java
@@ -20,7 +20,29 @@
 import com.aerospike.client.policy.Policy;
 
 /**
- * Batch key and record result.
+ * Base for a single key in a batch get, operate, delete, or UDF; holds key, record (or null), resultCode, and inDoubt flag.
+ * <p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchRead[] batchReads = new BatchRead[] {
+ *   new BatchRead(new Key("ns", "set", "k1"), new String[] { "bin1", "bin2" }),
+ *   new BatchRead(new Key("ns", "set", "k2"), true)
+ * };
+ * client.get(null, batchReads);
+ * for (BatchRead br : batchReads) {
+ *   if (br.record != null) { Object v = br.record.getValue("bin1"); }
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see BatchRead
+ * @see BatchWrite
+ * @see BatchDelete
+ * @see BatchUDF
+ * @see ResultCode
+ * @see com.aerospike.client.AerospikeException.BatchRecords
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.AerospikeClient#operate
  */
 public class BatchRecord {
 	/**
diff --git a/client/src/com/aerospike/client/BatchUDF.java b/client/src/com/aerospike/client/BatchUDF.java
index 665a264dd..0f386e5c1 100644
--- a/client/src/com/aerospike/client/BatchUDF.java
+++ b/client/src/com/aerospike/client/BatchUDF.java
@@ -25,7 +25,25 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Batch user defined functions.
+ * Batch UDF item: one key and a Lua module/function with optional arguments.
+ * <p>
+ * Pass an array to {@link com.aerospike.client.AerospikeClient#operate} (same as batch operate) or async overloads. Each element can use a different UDF or args.
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchUDF[] udfs = new BatchUDF[] {
+ *   new BatchUDF(new Key("ns", "set", "k1"), "mymodule", "myfunc", new Value[] { Value.get(1), Value.get("x") }),
+ *   new BatchUDF(new BatchUDFPolicy(), new Key("ns", "set", "k2"), "mymodule", "other", null)
+ * };
+ * client.operate(null, udfs);
+ * for (BatchUDF bu : udfs) {
+ *   if (bu.record != null) { Object result = bu.record.getValue("result"); }
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see BatchRecord
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.listener.BatchRecordArrayListener
  */
 public final class BatchUDF extends BatchRecord {
 	/**
diff --git a/client/src/com/aerospike/client/BatchWrite.java b/client/src/com/aerospike/client/BatchWrite.java
index b83c7e216..fc7d9a771 100644
--- a/client/src/com/aerospike/client/BatchWrite.java
+++ b/client/src/com/aerospike/client/BatchWrite.java
@@ -24,7 +24,30 @@
 import com.aerospike.client.policy.Policy;
 
 /**
- * Batch key and read/write operations with write policy.
+ * Batch operate item: one key with a list of read/write {@link Operation}s (put, delete, append, etc.).
+ * <p>
+ * Pass an array to {@link com.aerospike.client.AerospikeClient#operate} or async overloads with {@link com.aerospike.client.listener.BatchRecordArrayListener} / {@link com.aerospike.client.listener.BatchRecordSequenceListener}. Use {@link Operation#get(String)} per bin, not {@link Operation#get()}, so results align with operations.
+ * <pre>{@code
+ * AerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchWrite[] records = new BatchWrite[] {
+ *   new BatchWrite(new Key("ns", "set", "k1"), new Operation[] {
+ *     Operation.put(new Bin("a", 1)),
+ *     Operation.get("a")
+ *   }),
+ *   new BatchWrite(new Key("ns", "set", "k2"), new Operation[] { Operation.delete() })
+ * };
+ * client.operate(null, records);
+ * for (BatchWrite bw : records) {
+ *   if (bw.record != null) { Record r = bw.record; }
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see BatchRecord
+ * @see Operation
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.listener.BatchRecordArrayListener
+ * @see com.aerospike.client.listener.BatchRecordSequenceListener
  */
 public final class BatchWrite extends BatchRecord {
 	/**
diff --git a/client/src/com/aerospike/client/Bin.java b/client/src/com/aerospike/client/Bin.java
index f8de8ac93..d530fe538 100644
--- a/client/src/com/aerospike/client/Bin.java
+++ b/client/src/com/aerospike/client/Bin.java
@@ -24,7 +24,25 @@
 import com.aerospike.client.cdt.MapOrder;
 
 /**
- * Column name/value pair.
+ * Name/value pair for a single bin (column); used in put and operate calls.
+ * <p>
+ * Bin names are limited to {@link #MAX_BIN_NAME_LENGTH} characters. Use {@link Value} for typed values.
+ *
+ * <p><b>Example:</b>
+ * <p>Put a record with multiple bins using Bin name/value pairs.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Key key = new Key("test", "set1", "id1");
+ *   client.put(null, key, new Bin("name", "Alice"), new Bin("age", 30));
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see Value
+ * @see com.aerospike.client.AerospikeClient#put
+ * @see com.aerospike.client.AerospikeClient#operate
  */
 public final class Bin {
 	/**
@@ -246,19 +264,21 @@ public Bin(String name, Value value) {
 	}
 
 	/**
-	 * Create bin with a null value. This is useful for bin deletions within a record.
+	 * Create a bin with a null value (useful for bin deletions within a record).
 	 *
-	 * @param name		bin name, current limit is 15 characters
+	 * @param name bin name; current limit 15 characters; must not be null
+	 * @return a Bin whose value is null
 	 */
 	public static Bin asNull(String name) {
 		return new Bin(name, Value.getAsNull());
 	}
 
 	/**
-	 * Create bin with a GeoJSON value.
+	 * Create a bin with a GeoJSON string value.
 	 *
-	 * @param name		bin name, current limit is 15 characters
-	 * @param value		bin value
+	 * @param name  bin name; current limit 15 characters; must not be null
+	 * @param value GeoJSON string; must not be null
+	 * @return a Bin with GeoJSON value
 	 */
 	public static Bin asGeoJSON(String name, String value) {
 		return new Bin(name, Value.getAsGeoJSON(value));
diff --git a/client/src/com/aerospike/client/CommitError.java b/client/src/com/aerospike/client/CommitError.java
index 92be65dbc..68e2c8c64 100644
--- a/client/src/com/aerospike/client/CommitError.java
+++ b/client/src/com/aerospike/client/CommitError.java
@@ -17,7 +17,29 @@
 package com.aerospike.client;
 
 /**
- * Transaction error status.
+ * Transaction commit error code in {@link AerospikeException.Commit}; {@link #str} holds a human-readable message.
+ *
+ * <p><b>Example:</b>
+ * <p>Catch commit exception and handle CommitError (e.g. verify failure).</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   client.commit(txn);
+ * } catch (AerospikeException.Commit e) {
+ *   CommitError err = e.error;
+ *   switch (err) {
+ *     case VERIFY_FAIL:
+ *     case VERIFY_FAIL_CLOSE_ABANDONED:
+ *       break;
+ *     default:
+ *       System.err.println(err.str);
+ *   }
+ * }
+ * }</pre>
+ *
+ * @see AerospikeException.Commit
+ * @see CommitStatus
+ * @see AbortStatus
  */
 public enum CommitError {
 	VERIFY_FAIL("Transaction verify failed. Transaction aborted."),
@@ -25,6 +47,7 @@ public enum CommitError {
 	VERIFY_FAIL_ABORT_ABANDONED("Transaction verify failed. Transaction client abort abandoned. Server will eventually abort the transaction."),
 	MARK_ROLL_FORWARD_ABANDONED("Transaction client mark roll forward abandoned. Server will eventually abort the transaction.");
 
+	/** Human-readable message for this error. */
 	public final String str;
 
 	CommitError(String str) {
diff --git a/client/src/com/aerospike/client/CommitStatus.java b/client/src/com/aerospike/client/CommitStatus.java
index 435192827..76714d2d9 100644
--- a/client/src/com/aerospike/client/CommitStatus.java
+++ b/client/src/com/aerospike/client/CommitStatus.java
@@ -17,7 +17,27 @@
 package com.aerospike.client;
 
 /**
- * Transaction commit status code.
+ * Transaction commit result returned by {@link com.aerospike.client.AerospikeClient#commit}. OK and ALREADY_COMMITTED indicate success; abandoned statuses mean the server will complete asynchronously.
+ *
+ * <p><b>Example:</b>
+ * <p>Commit a transaction and handle the returned status (OK, abandoned, etc.).</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * CommitStatus status = client.commit(txn);
+ * switch (status) {
+ *   case OK:
+ *   case ALREADY_COMMITTED:
+ *     break;
+ *   case ROLL_FORWARD_ABANDONED:
+ *   case CLOSE_ABANDONED:
+ *     System.err.println(status.str);
+ *     break;
+ * }
+ * }</pre>
+ *
+ * @see AbortStatus
+ * @see CommitError
+ * @see com.aerospike.client.AerospikeClient#commit
  */
 public enum CommitStatus {
 	OK("Commit succeeded"),
@@ -25,6 +45,7 @@ public enum CommitStatus {
 	ROLL_FORWARD_ABANDONED("Transaction client roll forward abandoned. Server will eventually commit the transaction."),
 	CLOSE_ABANDONED("Transaction has been rolled forward, but transaction client close was abandoned. Server will eventually close the transaction.");
 
+	/** Human-readable message for this status. */
 	public final String str;
 
 	CommitStatus(String str) {
diff --git a/client/src/com/aerospike/client/Host.java b/client/src/com/aerospike/client/Host.java
index a4c9e16e7..0ad8d8e35 100644
--- a/client/src/com/aerospike/client/Host.java
+++ b/client/src/com/aerospike/client/Host.java
@@ -20,7 +20,21 @@
 import java.util.List;
 
 /**
- * Host name/port of database server.
+ * Host name and port (and optional TLS name) for a database server; used as seed for {@link com.aerospike.client.AerospikeClient} and parsed by {@link #parseHosts}.
+ * <p>
+ * Format for parsing: {@code hostname[:tlsname][:port],...}. Use {@link #parseHosts(String, int)} or {@link #parseServiceHosts(String)} to build a list.
+ *
+ * <p><b>Example:</b>
+ * <p>Parse host string and port into Host array and create a client.</p>
+ * <pre>{@code
+ * Host[] hosts = Host.parseHosts("localhost", 3000);
+ * IAerospikeClient client = new AerospikeClient(new ClientPolicy(), hosts);
+ * client.close();
+ * }</pre>
+ *
+ * @see #parseHosts
+ * @see #parseServiceHosts
+ * @see com.aerospike.client.AerospikeClient
  */
 public final class Host {
 	/**
@@ -95,6 +109,11 @@ public boolean equals(Object obj) {
 	 * </ul>
 	 * IPv6 addresses must be enclosed by brackets.
 	 * tlsname and port are optional.
+	 *
+	 * @param str         comma-separated host[:tls][:port] list; must not be null
+	 * @param defaultPort port when not specified per host
+	 * @return array of Host; never null
+	 * @throws AerospikeException when the string format is invalid (e.g. missing host:port or bad port).
 	 */
 	public static Host[] parseHosts(String str, int defaultPort) {
 		try {
@@ -115,6 +134,10 @@ public static Host[] parseHosts(String str, int defaultPort) {
 	 * <li>IPv6: [xxxx::xxxx]</li>
 	 * </ul>
 	 * IPv6 addresses must be enclosed by brackets.
+	 *
+	 * @param str hostname:port comma-separated list; must not be null
+	 * @return list of Host; never null
+	 * @throws AerospikeException when the string format is invalid (e.g. missing host:port or bad port).
 	 */
 	public static List<Host> parseServiceHosts(String str) {
 		try {
diff --git a/client/src/com/aerospike/client/IAerospikeClient.java b/client/src/com/aerospike/client/IAerospikeClient.java
index 5c6aea04c..e6d7fc636 100644
--- a/client/src/com/aerospike/client/IAerospikeClient.java
+++ b/client/src/com/aerospike/client/IAerospikeClient.java
@@ -76,6 +76,8 @@
 /**
  * This interface's sole purpose is to allow mock frameworks to operate on
  * AerospikeClient without being constrained by final methods.
+ *
+ * @see AerospikeClient
  */
 public interface IAerospikeClient extends Closeable {
 	/**
diff --git a/client/src/com/aerospike/client/Info.java b/client/src/com/aerospike/client/Info.java
index e77c4705c..374b688b5 100644
--- a/client/src/com/aerospike/client/Info.java
+++ b/client/src/com/aerospike/client/Info.java
@@ -29,13 +29,26 @@
 import com.aerospike.client.util.Crypto;
 
 /**
- * Access server's info monitoring protocol.
+ * Access the server info monitoring protocol (name/value pairs from a node).
  * <p>
- * The info protocol is a name/value pair based system, where an individual
- * database server node is queried to determine its configuration and status.
- * The list of supported names can be found at:
- * <p>
- * <a href="https://www.aerospike.com/docs/reference/info/index.html">https://www.aerospike.com/docs/reference/info/index.html</a>
+ * Query a single node for configuration and status. Supported command names: <a href="https://www.aerospike.com/docs/reference/info/index.html">Aerospike Info Reference</a>.
+ *
+ * <p><b>Example:</b>
+ * <p>Request info from a node (e.g. "build" or "statistics").</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Node node = client.getNodes()[0];
+ *   String build = Info.request(node, "build");
+ *   Map m = Info.request(null, node, "build", "statistics");
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see #request(Node, String)
+ * @see #request(InfoPolicy, Node, String)
+ * @see #request(InfoPolicy, Node, String...)
  */
 public class Info {
 	//-------------------------------------------------------
@@ -50,10 +63,11 @@ public class Info {
 
 	/**
 	 * Get one info value by name from the specified database server node.
-	 * This method supports user authentication.
 	 *
-	 * @param node		server node
-	 * @param name		name of variable to retrieve
+	 * @param node server node; must not be null
+	 * @param name name of the info variable (e.g. "build", "statistics")
+	 * @return the value string for the requested name
+	 * @throws AerospikeException when the request fails (e.g. timeout, connection error, or invalid command).
 	 */
 	public static String request(Node node, String name) throws AerospikeException {
 		Connection conn = node.getConnection(DEFAULT_TIMEOUT);
diff --git a/client/src/com/aerospike/client/Key.java b/client/src/com/aerospike/client/Key.java
index f03e098c0..b453fdb2c 100644
--- a/client/src/com/aerospike/client/Key.java
+++ b/client/src/com/aerospike/client/Key.java
@@ -22,10 +22,28 @@
 import com.aerospike.client.util.Crypto;
 
 /**
- * Unique record identifier. Records can be identified using a specified namespace,
- * an optional set name, and a user defined key which must be unique within a set.
- * Records can also be identified by namespace/digest which is the combination used
- * on the server.
+ * Unique record identifier: namespace, optional set name, and user key (or namespace/digest on the server).
+ * <p>
+ * The user key is hashed to a digest; set {@link com.aerospike.client.policy.WritePolicy#sendKey} to store/retrieve the key on the server.
+ *
+ * <p><b>Example:</b>
+ * <p>Create a key and use it to get a record.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Key key = new Key("test", "set1", "id1");
+ *   Record rec = client.get(null, key);
+ *   if (rec != null) {
+ *     String name = (String) rec.getValue("name");
+ *   }
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see Record
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.policy.WritePolicy#sendKey
  */
 public final class Key {
 	/**
@@ -83,7 +101,7 @@ public final class Key {
 	 * @param namespace				namespace
 	 * @param setName				optional set name, enter null when set does not exist
 	 * @param key					user defined unique identifier within set.
-	 * @throws AerospikeException	if digest computation fails
+	 * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
 	 */
 	public Key(String namespace, String setName, String key) throws AerospikeException {
 		this.namespace = namespace;
@@ -119,7 +137,7 @@ public Key(String namespace, String setName, String key) throws AerospikeExcepti
 	 * @param namespace				namespace
 	 * @param setName				optional set name, enter null when set does not exist
 	 * @param key					user defined unique identifier within set.
-	 * @throws AerospikeException	if digest computation fails
+	 * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
 	 */
 	public Key(String namespace, String setName, byte[] key) throws AerospikeException {
 		this.namespace = namespace;
@@ -157,7 +175,7 @@ public Key(String namespace, String setName, byte[] key) throws AerospikeExcepti
 	 * @param key					user defined unique identifier within set.
 	 * @param offset				byte array segment offset
 	 * @param length				byte array segment length
-	 * @throws AerospikeException	if digest computation fails
+	 * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
 	 */
 	public Key(String namespace, String setName, byte[] key, int offset, int length) throws AerospikeException {
 		this.namespace = namespace;
@@ -180,7 +198,7 @@ public Key(String namespace, String setName, byte[] key, int offset, int length)
 	 * @param namespace				namespace
 	 * @param setName				optional set name, enter null when set does not exist
 	 * @param key					user defined unique identifier within set.
-	 * @throws AerospikeException	if digest computation fails
+	 * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
 	 */
 	public Key(String namespace, String setName, int key) throws AerospikeException {
 		this.namespace = namespace;
@@ -203,7 +221,7 @@ public Key(String namespace, String setName, int key) throws AerospikeException
 	 * @param namespace				namespace
 	 * @param setName				optional set name, enter null when set does not exist
 	 * @param key					user defined unique identifier within set.
-	 * @throws AerospikeException	if digest computation fails
+	 * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
 	 */
 	public Key(String namespace, String setName, long key) throws AerospikeException {
 		this.namespace = namespace;
@@ -226,7 +244,7 @@ public Key(String namespace, String setName, long key) throws AerospikeException
 	 * @param namespace				namespace
 	 * @param setName				optional set name, enter null when set does not exist
 	 * @param key					user defined unique identifier within set.
-	 * @throws AerospikeException	if digest computation fails
+	 * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
 	 */
 	public Key(String namespace, String setName, Value key) throws AerospikeException {
 		this.namespace = namespace;
@@ -309,8 +327,8 @@ public boolean equals(Object obj) {
 	 *
 	 * @param setName				optional set name, enter null when set does not exist
 	 * @param key					record identifier, unique within set
-	 * @return						unique server hash value
-	 * @throws AerospikeException	if digest computation fails
+	 * @return unique server hash value (RIPEMD-160 digest)
+	 * @throws AerospikeException when digest computation fails (e.g. unsupported or invalid key type).
 	 */
 	public static byte[] computeDigest(String setName, Value key) throws AerospikeException {
 		return Crypto.computeDigest(setName, key);
diff --git a/client/src/com/aerospike/client/Language.java b/client/src/com/aerospike/client/Language.java
index 625a23ce6..692915235 100644
--- a/client/src/com/aerospike/client/Language.java
+++ b/client/src/com/aerospike/client/Language.java
@@ -17,11 +17,25 @@
 package com.aerospike.client;
 
 /**
- * User defined function languages.
+ * UDF language identifier; used when registering or executing user-defined functions.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#register} for UDF package registration.
+ *
+ * <p><b>Example:</b>
+ * <p>Register a UDF package using Language.LUA.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   com.aerospike.client.task.RegisterTask task = client.register(null, "myudf.lua", "myudf.lua", Language.LUA);
+ *   task.waitTillComplete();
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient#register
  */
 public enum Language {
-	/**
-	 * Lua embedded programming language.
-	 */
+	/** Lua embedded programming language. */
 	LUA;
 }
diff --git a/client/src/com/aerospike/client/Operation.java b/client/src/com/aerospike/client/Operation.java
index 6bb342fc7..e437840a2 100644
--- a/client/src/com/aerospike/client/Operation.java
+++ b/client/src/com/aerospike/client/Operation.java
@@ -17,7 +17,25 @@
 package com.aerospike.client;
 
 /**
- * Database operation definition.  The class is used in client's operate() method.
+ * Single operation in a multi-op request; use static factories and pass to {@link com.aerospike.client.AerospikeClient#operate}.
+ * <p>
+ * Supports read (get, getHeader), write (put, append, prepend, add), touch, and delete. Multiple operations are executed atomically.
+ *
+ * <p><b>Example:</b>
+ * <p>Atomically add to a bin and read it back using operate.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Key key = new Key("test", "set1", "id1");
+ *   Record rec = client.operate(null, key, Operation.add(new Bin("count", 1)), Operation.get("count"));
+ *   long count = rec.getLong("count");
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see Bin
  */
 public final class Operation {
 	/**
diff --git a/client/src/com/aerospike/client/Record.java b/client/src/com/aerospike/client/Record.java
index f2d1293fb..3270bb210 100644
--- a/client/src/com/aerospike/client/Record.java
+++ b/client/src/com/aerospike/client/Record.java
@@ -25,7 +25,30 @@
 import com.aerospike.client.Value.HLLValue;
 
 /**
- * Container object for records.  Records are equivalent to rows.
+ * Container for a record's bins and metadata (generation, expiration); returned by get, query, and scan.
+ * <p>
+ * Use {@link #getValue(String)} or typed getters such as {@link #getString(String)}, {@link #getLong(String)} to read bins.
+ *
+ * <p><b>Example:</b>
+ * <p>Read a record and access bins with getString/getLong.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Key key = new Key("test", "set1", "id1");
+ *   Record rec = client.get(null, key);
+ *   if (rec != null) {
+ *     String name = rec.getString("name");
+ *     long age = rec.getLong("age");
+ *   }
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see Key
+ * @see #getValue
+ * @see #getString
+ * @see com.aerospike.client.AerospikeClient#get
  */
 public final class Record {
 	/**
@@ -57,7 +80,10 @@ public Record(
 	}
 
 	/**
-	 * Get bin value given bin name.
+	 * Get bin value by name.
+	 *
+	 * @param name bin name; must not be null
+	 * @return the bin value, or null if absent or bins is null
 	 */
 	public Object getValue(String name) {
 		return (bins == null)? null : bins.get(name);
@@ -65,6 +91,9 @@ public Object getValue(String name) {
 
 	/**
 	 * Get bin value as String.
+	 *
+	 * @param name bin name; must not be null
+	 * @return the bin value as String, or null if absent or not a string
 	 */
 	public String getString(String name) {
 		return (String)getValue(name);
diff --git a/client/src/com/aerospike/client/ResultCode.java b/client/src/com/aerospike/client/ResultCode.java
index ba90d0ee5..6af1856ea 100644
--- a/client/src/com/aerospike/client/ResultCode.java
+++ b/client/src/com/aerospike/client/ResultCode.java
@@ -17,8 +17,25 @@
 package com.aerospike.client;
 
 /**
- * Database operation error codes.  The positive numbers align with the server
- * side file proto.h.
+ * Database operation result/error codes; positive values align with server proto.h, negative values are client-side.
+ * <p>
+ * Use {@link AerospikeException#getResultCode()} and {@link #getResultString(int)} to interpret failures.
+ *
+ * <p><b>Example:</b>
+ * <p>Get result code and message from an AerospikeException after a failed put.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   client.put(null, key, bins);
+ * } catch (AerospikeException e) {
+ *   int code = e.getResultCode();
+ *   String msg = ResultCode.getResultString(code);
+ * }
+ * }</pre>
+ *
+ * @see AerospikeException#getResultCode
+ * @see #getResultString(int)
+ * @see #keepConnection(int)
  */
 public final class ResultCode {
 	/**
diff --git a/client/src/com/aerospike/client/ScanCallback.java b/client/src/com/aerospike/client/ScanCallback.java
index 5040e299a..755decce5 100644
--- a/client/src/com/aerospike/client/ScanCallback.java
+++ b/client/src/com/aerospike/client/ScanCallback.java
@@ -20,12 +20,29 @@
  * An object implementing this interface is passed in <code>scan()</code> calls, so the caller can
  * be notified with scan results.
  * @deprecated
- * <p>Use {@link com.aerospike.client.query.QueryListener} with
- *    {@link com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.QueryListener)}
- *    instead. create a {@link com.aerospike.client.query.Statement} with the same namespace and set name (no filter),
- *    set bin names if needed, then call {@code query(queryPolicy, statement, queryListener)}.
- *    For partition-scoped reads use {@link com.aerospike.client.AerospikeClient#queryPartitions(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.PartitionFilter)}.
- * </p>
+ * <p>Use {@link com.aerospike.client.query.QueryListener} with {@link com.aerospike.client.AerospikeClient#query}
+ * instead.Create a {@link com.aerospike.client.query.Statement} with the same namespace and set name (no filter),
+ * then call {@code query(queryPolicy, statement, queryListener)}. For partition-scoped reads use
+ * {@link com.aerospike.client.AerospikeClient#queryPartitions}.
+ *
+ * <p><b>Example (deprecated; prefer query with QueryListener):</b>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   ScanCallback callback = (key, record) -> {
+ *     if (record != null) {
+ *       Object val = record.getValue("mybin");
+ *     }
+ *   };
+ *   client.scanAll(null, "test", "set1", callback, "mybin");
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see com.aerospike.client.query.QueryListener
+ * @see com.aerospike.client.AerospikeClient#query
+ * @see com.aerospike.client.AerospikeClient#queryPartitions
  */
 @Deprecated
 public interface ScanCallback {
@@ -36,13 +53,11 @@ public interface ScanCallback {
 	 * to other nodes will also be terminated and the exception will be propagated back through the
 	 * initiating scan call.
 	 * <p>
-	 * If {@link com.aerospike.client.policy.ScanPolicy#concurrentNodes} is true and
-	 * {@link com.aerospike.client.policy.ScanPolicy#maxConcurrentNodes} is not equal one, then
-	 * your scanCallback implementation must be thread safe.
+	 * If {@link com.aerospike.client.policy.ScanPolicy#concurrentNodes} is true and maxConcurrentNodes is not one, the implementation must be thread-safe.
 	 *
-	 * @param key					unique record identifier
-	 * @param record				container for bins and record meta-data
-	 * @throws AerospikeException	if error occurs or scan should be terminated.
+	 * @param key    unique record identifier; never null
+	 * @param record container for bins and metadata; never null
+	 * @throws AerospikeException when the callback wishes to abort the scan or report an error (e.g. throw ScanTerminated to abort).
 	 */
 	public void scanCallback(Key key, Record record) throws AerospikeException;
 }
diff --git a/client/src/com/aerospike/client/Txn.java b/client/src/com/aerospike/client/Txn.java
index 17823bd8a..9fb658eaf 100644
--- a/client/src/com/aerospike/client/Txn.java
+++ b/client/src/com/aerospike/client/Txn.java
@@ -23,12 +23,32 @@
 import java.util.concurrent.atomic.AtomicLong;
 
 /**
- * Multi-record transaction. Each command in the transaction must use the same namespace.
+ * Multi-record transaction; all commands must use the same namespace. Set {@link com.aerospike.client.policy.Policy#txn} on the write policy, then call {@link com.aerospike.client.AerospikeClient#commit} or {@link com.aerospike.client.AerospikeClient#abort}.
+ *
+ * <p><b>Example:</b>
+ * <p>Run a multi-record transaction: get, put with txn policy, then commit.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Txn txn = new Txn();
+ *   WritePolicy wp = client.getWritePolicyDefault().copy();
+ *   wp.txn = txn;
+ *   Key k1 = new Key("test", "set1", "id1");
+ *   Key k2 = new Key("test", "set1", "id2");
+ *   client.get(null, k1);
+ *   client.put(wp, k2, new Bin("x", 1));
+ *   CommitStatus status = client.commit(txn);
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see com.aerospike.client.policy.Policy#txn
+ * @see com.aerospike.client.AerospikeClient#commit
+ * @see com.aerospike.client.AerospikeClient#abort
  */
 public final class Txn {
-	/**
-	 * Transaction state.
-	 */
+	/** Transaction state. */
 	public static enum State {
 		OPEN,
 		VERIFIED,
diff --git a/client/src/com/aerospike/client/Value.java b/client/src/com/aerospike/client/Value.java
index 0dc598846..9673798c3 100644
--- a/client/src/com/aerospike/client/Value.java
+++ b/client/src/com/aerospike/client/Value.java
@@ -39,7 +39,49 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Polymorphic value classes used to efficiently serialize objects into the wire protocol.
+ * Polymorphic value type used to serialize objects for the wire protocol; use static {@code get()} factories to obtain instances.
+ * <p>
+ * Concrete types represent strings, numbers, blobs, lists, maps, GeoJSON, etc. Use with {@link Bin} and
+ * {@link com.aerospike.client.AerospikeClient#put}, {@link com.aerospike.client.AerospikeClient#operate}, and expression APIs.
+ * <p>
+ * Concrete value types (child classes): {@link NullValue}, {@link BytesValue}, {@link ByteSegmentValue}, {@link ByteValue},
+ * {@link StringValue}, {@link ShortValue}, {@link IntegerValue}, {@link LongValue}, {@link DoubleValue}, {@link FloatValue},
+ * {@link BooleanValue}, {@link BoolIntValue}, {@link GeoJSONValue}, {@link HLLValue}, {@link ValueArray}, {@link ListValue},
+ * {@link MapValue}, {@link SortedMapValue}, {@link InfinityValue}, and {@link WildcardValue}.
+ *
+ * <p><b>Example:</b>
+ * <p>Put a record with string and integer bins using IAerospikeClient.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Key key = new Key("test", "set1", "id1");
+ *   client.put(null, key, new Bin("name", Value.get("Alice")), new Bin("age", Value.get(30)));
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see NullValue
+ * @see BytesValue
+ * @see ByteSegmentValue
+ * @see ByteValue
+ * @see StringValue
+ * @see ShortValue
+ * @see IntegerValue
+ * @see LongValue
+ * @see DoubleValue
+ * @see FloatValue
+ * @see BooleanValue
+ * @see BoolIntValue
+ * @see GeoJSONValue
+ * @see HLLValue
+ * @see ValueArray
+ * @see ListValue
+ * @see MapValue
+ * @see SortedMapValue
+ * @see InfinityValue
+ * @see WildcardValue
+ * @see Bin
  */
 public abstract class Value {
 	/**
@@ -397,6 +439,13 @@ public long toLong() {
 
 	/**
 	 * Empty value.
+	 * <p><b>Example:</b>
+	 * <p>Store a null bin using Value.getAsNull().</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("test", "set1", "id1");
+	 * client.put(null, key, new Bin("optional", Value.getAsNull()));
+	 * }</pre>
 	 */
 	public static final class NullValue extends Value {
 		public static final NullValue INSTANCE = new NullValue();
@@ -457,6 +506,13 @@ public final int hashCode() {
 
 	/**
 	 * Byte array value.
+	 * <p><b>Example:</b>
+	 * <p>Store a blob bin with Value.get(byte[]).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * Key key = new Key("test", "set1", "id1");
+	 * client.put(null, key, new Bin("blob", Value.get(new byte[] { 1, 2, 3 })));
+	 * }</pre>
 	 */
 	public static final class BytesValue extends Value {
 		private final byte[] bytes;
@@ -528,6 +584,13 @@ public int hashCode() {
 
 	/**
 	 * Byte segment value.
+	 * <p><b>Example:</b>
+	 * <p>Store a byte segment with Value.get(array, offset, length).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * byte[] buf = new byte[] { 0, 1, 2, 3, 4 };
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("seg", Value.get(buf, 1, 3)));
+	 * }</pre>
 	 */
 	public static final class ByteSegmentValue extends Value {
 		private final byte[] bytes;
@@ -628,6 +691,12 @@ public int getLength() {
 
 	/**
 	 * Byte value.
+	 * <p><b>Example:</b>
+	 * <p>Store a byte bin with Value.get(byte).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("flag", Value.get((byte) 1)));
+	 * }</pre>
 	 */
 	public static final class ByteValue extends Value {
 		private final byte value;
@@ -703,6 +772,12 @@ public long toLong() {
 
 	/**
 	 * String value.
+	 * <p><b>Example:</b>
+	 * <p>Store a string bin with Value.get(String).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("name", Value.get("Alice")));
+	 * }</pre>
 	 */
 	public static final class StringValue extends Value {
 		private final String value;
@@ -766,6 +841,12 @@ public int hashCode() {
 
 	/**
 	 * Short value.
+	 * <p><b>Example:</b>
+	 * <p>Store a short bin with Value.get(short).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("count", Value.get((short) 100)));
+	 * }</pre>
 	 */
 	public static final class ShortValue extends Value {
 		private final short value;
@@ -840,6 +921,12 @@ public long toLong() {
 
 	/**
 	 * Integer value.
+	 * <p><b>Example:</b>
+	 * <p>Store an integer bin with Value.get(int).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("age", Value.get(30)));
+	 * }</pre>
 	 */
 	public static final class IntegerValue extends Value {
 		private final int value;
@@ -914,6 +1001,12 @@ public long toLong() {
 
 	/**
 	 * Long value.
+	 * <p><b>Example:</b>
+	 * <p>Store a long bin with Value.get(long).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("timestamp", Value.get(1234567890L)));
+	 * }</pre>
 	 */
 	public static final class LongValue extends Value {
 		private final long value;
@@ -988,6 +1081,12 @@ public long toLong() {
 
 	/**
 	 * Double value.
+	 * <p><b>Example:</b>
+	 * <p>Store a double bin with Value.get(double).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("score", Value.get(3.14)));
+	 * }</pre>
 	 */
 	public static final class DoubleValue extends Value {
 		private final double value;
@@ -1063,6 +1162,12 @@ public long toLong() {
 
 	/**
 	 * Float value.
+	 * <p><b>Example:</b>
+	 * <p>Store a float bin with Value.get(float).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("rate", Value.get(1.5f)));
+	 * }</pre>
 	 */
 	public static final class FloatValue extends Value {
 		private final float value;
@@ -1137,6 +1242,12 @@ public long toLong() {
 
 	/**
 	 * Boolean value.
+	 * <p><b>Example:</b>
+	 * <p>Store a boolean bin with Value.get(boolean).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("active", Value.get(true)));
+	 * }</pre>
 	 */
 	public static final class BooleanValue extends Value {
 		private final boolean value;
@@ -1213,6 +1324,13 @@ public long toLong() {
 	 * Boolean value that converts to integer when sending a bin to the server.
 	 * This class will be deleted once full conversion to boolean particle type
 	 * is complete.
+	 * <p><b>Example:</b>
+	 * <p>Store boolean as integer when UseBoolBin is false.</p>
+	 * <pre>{@code
+	 * Value.UseBoolBin = false;
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("flag", Value.get(false)));
+	 * }</pre>
 	 */
 	public static final class BoolIntValue extends Value {
 		private final boolean value;
@@ -1288,6 +1406,13 @@ public long toLong() {
 
 	/**
 	 * GeoJSON value.
+	 * <p><b>Example:</b>
+	 * <p>Store a GeoJSON bin with Value.getAsGeoJSON(String).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"),
+	 *     new Bin("loc", Value.getAsGeoJSON("{\"type\":\"Point\",\"coordinates\":[-122.0,37.5]}")));
+	 * }</pre>
 	 */
 	public static final class GeoJSONValue extends Value {
 		private final String value;
@@ -1354,6 +1479,12 @@ public int hashCode() {
 
 	/**
 	 * HyperLogLog value.
+	 * <p><b>Example:</b>
+	 * <p>Store an HLL bin with Value.getAsHLL(byte[]).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("hll", Value.getAsHLL(hllBytes)));
+	 * }</pre>
 	 */
 	public static final class HLLValue extends Value {
 		private final byte[] bytes;
@@ -1422,6 +1553,13 @@ public int hashCode() {
 
 	/**
 	 * Value array.
+	 * <p><b>Example:</b>
+	 * <p>Store a list bin from Value array with Value.get(Value[]).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"),
+	 *     new Bin("arr", Value.get(new Value[] { Value.get(1), Value.get("x") })));
+	 * }</pre>
 	 */
 	public static final class ValueArray extends Value {
 		private final Value[] array;
@@ -1488,6 +1626,13 @@ public int hashCode() {
 
 	/**
 	 * List value.
+	 * <p><b>Example:</b>
+	 * <p>Store a list bin with Value.get(List).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * client.put(null, new Key("test", "set1", "id1"),
+	 *     new Bin("tags", Value.get(Arrays.asList("a", "b", "c"))));
+	 * }</pre>
 	 */
 	public static final class ListValue extends Value {
 		private final List<?> list;
@@ -1554,6 +1699,14 @@ public int hashCode() {
 
 	/**
 	 * Map value.
+	 * <p><b>Example:</b>
+	 * <p>Store a map bin with Value.get(Map).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * java.util.Map<String, Integer> map = new java.util.HashMap<>();
+	 * map.put("x", 1);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("data", Value.get(map)));
+	 * }</pre>
 	 */
 	public static final class MapValue extends Value {
 		private final Map<?,?> map;
@@ -1635,6 +1788,14 @@ public static MapOrder getMapOrder(Map<?,?> map) {
 
 	/**
 	 * Sorted map value.
+	 * <p><b>Example:</b>
+	 * <p>Store a sorted map bin with Value.get(SortedMap).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * java.util.SortedMap<String, Integer> map = new java.util.TreeMap<>();
+	 * map.put("a", 1);
+	 * client.put(null, new Key("test", "set1", "id1"), new Bin("data", Value.get(map)));
+	 * }</pre>
 	 */
 	public static final class SortedMapValue extends Value {
 		private final List<? extends Entry<?,?>> list;
@@ -1704,7 +1865,13 @@ public int hashCode() {
 	}
 
 	/**
-	 * Infinity value.
+	 * Infinity value to be used in CDT range comparisons only.
+	 * <p><b>Example:</b>
+	 * <p>Use Value.INFINITY in map/list range operations (e.g. getByValueRange).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * // Use Value.INFINITY in map/list range operations, e.g. getByValueRange(Value.INFINITY, Value.INFINITY)
+	 * }</pre>
 	 */
 	public static final class InfinityValue extends Value {
 		@Override
@@ -1760,7 +1927,13 @@ public final int hashCode() {
 	}
 
 	/**
-	 * Wildcard value.
+	 * Wildcard value to be used in CDT range comparisons only.
+	 * <p><b>Example:</b>
+	 * <p>Use Value.WILDCARD in map/list range operations (e.g. getByValueRange).</p>
+	 * <pre>{@code
+	 * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+	 * // Use Value.WILDCARD in map/list range operations, e.g. getByValueRange(Value.WILDCARD, Value.WILDCARD)
+	 * }</pre>
 	 */
 	public static final class WildcardValue extends Value {
 		@Override
diff --git a/client/src/com/aerospike/client/admin/Privilege.java b/client/src/com/aerospike/client/admin/Privilege.java
index 3cb1fcb2c..a79b691a3 100644
--- a/client/src/com/aerospike/client/admin/Privilege.java
+++ b/client/src/com/aerospike/client/admin/Privilege.java
@@ -17,23 +17,37 @@
 package com.aerospike.client.admin;
 
 /**
- * User privilege.
+ * Single privilege (code plus optional namespace/set scope) for role-based access; use in {@link com.aerospike.client.AerospikeClient#createRole} and {@link com.aerospike.client.AerospikeClient#grantPrivileges}.
+ * <p>
+ * Set {@link #namespace} and {@link #setName} to null for global scope when the privilege allows it; use {@link PrivilegeCode#canScope()} to check.
+ *
+ * <p><b>Example:</b>
+ * <p>Create a privilege with namespace scope and use it in createRole.</p>
+ * <pre>{@code
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.READ_WRITE;
+ * p.namespace = "test";
+ * p.setName = null;
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   client.createRole(null, "myrole", Collections.singletonList(p));
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see PrivilegeCode
+ * @see com.aerospike.client.AerospikeClient#createRole
+ * @see com.aerospike.client.AerospikeClient#grantPrivileges
+ * @see com.aerospike.client.AerospikeClient#revokePrivileges
  */
 public final class Privilege {
-	/**
-	 * Privilege code.
-	 */
+	/** Privilege type; must not be null. */
 	public PrivilegeCode code;
 
-	/**
-	 *	Namespace scope. Apply permission to this namespace only.
-	 *	If namespace is null, the privilege applies to all namespaces.
-	 */
+	/** Namespace scope; null means all namespaces (when privilege allows). */
 	public String namespace;
 
-	/**
-	 *	Set name scope. Apply permission to this set within namespace only.
-	 *	If set is null, the privilege applies to all sets within namespace.
-	 */
+	/** Set name scope within namespace; null means all sets in the namespace. */
 	public String setName;
 }
diff --git a/client/src/com/aerospike/client/admin/PrivilegeCode.java b/client/src/com/aerospike/client/admin/PrivilegeCode.java
index acf760c8b..e3f0369f3 100644
--- a/client/src/com/aerospike/client/admin/PrivilegeCode.java
+++ b/client/src/com/aerospike/client/admin/PrivilegeCode.java
@@ -19,7 +19,23 @@
 import com.aerospike.client.AerospikeException;
 
 /**
- * Permission codes define the type of permission granted for a user's role.
+ * Permission codes for role privileges (read, write, admin, etc.); use with {@link Privilege} in createRole and grantPrivileges.
+ * <p>
+ * Use {@link #fromId(int)} to map server-returned IDs; use {@link #canScope()} to see if namespace/set scope applies.
+ *
+ * <p><b>Example:</b>
+ * <p>Create a role with READ_WRITE privilege scoped to a namespace.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Privilege p = new Privilege();
+ * p.code = PrivilegeCode.READ_WRITE;
+ * p.namespace = "test";
+ * client.createRole(null, "myrole", java.util.Collections.singletonList(p));
+ * }</pre>
+ *
+ * @see Privilege
+ * @see com.aerospike.client.AerospikeClient#createRole
+ * @see com.aerospike.client.AerospikeClient#grantPrivileges
  */
 public enum PrivilegeCode {
 	/**
@@ -107,7 +123,9 @@ private PrivilegeCode(int id, String value) {
 	}
 
 	/**
-	 * Can privilege be scoped with namespace and set.
+	 * Whether this privilege can be scoped with namespace and set (data privileges); global-only privileges return false.
+	 *
+	 * @return true if namespace/set scope can be applied
 	 */
 	public boolean canScope() {
 		// Unknown privileges cannot be scoped since we don't know their characteristics
@@ -117,9 +135,11 @@ public boolean canScope() {
 	}
 
 	/**
-	 * Convert ID to privilege code enum.
-	 * Returns UNKNOWN for unrecognized privilege codes to support
-	 * forward compatibility with newer server versions.
+	 * Convert wire-protocol privilege ID to enum.
+	 *
+	 * @param id privilege ID from server (e.g. 10 for READ, 11 for READ_WRITE)
+	 * @return the corresponding PrivilegeCode
+	 * @throws AerospikeException when the given ID is not a known privilege code (invalid or reserved).
 	 */
 	public static PrivilegeCode fromId(int id) {
 		switch (id) {
diff --git a/client/src/com/aerospike/client/admin/Role.java b/client/src/com/aerospike/client/admin/Role.java
index 2f0349171..950fe1b88 100644
--- a/client/src/com/aerospike/client/admin/Role.java
+++ b/client/src/com/aerospike/client/admin/Role.java
@@ -19,97 +19,83 @@
 import java.util.List;
 
 /**
- * Role definition.
+ * Role definition: name, privileges, optional whitelist and read/write quotas. Returned by {@link com.aerospike.client.AerospikeClient#queryRole}; privilege list is used in createRole and grantPrivileges.
+ * <p>
+ * Use the static constants (e.g. {@link #Read}, {@link #ReadWrite}) as role names when creating users; use {@link Privilege} for fine-grained role definitions.
+ *
+ * <p><b>Example:</b>
+ * <p>Query a role and read its name and privileges.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   Role role = client.queryRole(null, "myrole");
+ *   if (role != null) {
+ *     String name = role.name;
+ *     List privs = role.privileges;
+ *   }
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see Privilege
+ * @see com.aerospike.client.AerospikeClient#queryRole
+ * @see com.aerospike.client.AerospikeClient#queryRoles
+ * @see com.aerospike.client.AerospikeClient#createRole
  */
 public final class Role {
-	/**
-	 * Manage users their roles.
-	 */
+	/** Role name for user administration. */
 	public static final String UserAdmin = "user-admin";
 
-	/**
-	 * Manage server configuration.
-	 */
+	/** Role name for server configuration. */
 	public static final String SysAdmin = "sys-admin";
 
-	/**
-	 * Manage user defined functions and indicies.
-	 */
+	/** Role name for UDF and index administration. */
 	public static final String DataAdmin = "data-admin";
 
-	/**
-	 * Manage user defined functions.
-	 */
+	/** Role name for UDF administration. */
 	public static final String UDFAdmin = "udf-admin";
 
-	/**
-	 * Manage indicies.
-	 */
+	/** Role name for index administration. */
 	public static final String SIndexAdmin = "sindex-admin";
 
-	/**
-	 * Allow read commands.
-	 */
+	/** Role name for read-only access. */
 	public static final String Read = "read";
 
-	/**
-	 * Allow read and write commands.
-	 */
+	/** Role name for read and write access. */
 	public static final String ReadWrite = "read-write";
 
-	/**
-	 * Allow read and write commands within user defined functions.
-	 */
+	/** Role name for read/write via UDF. */
 	public static final String ReadWriteUdf = "read-write-udf";
 
-	/**
-	 * Allow write commands.
-	 */
+	/** Role name for write-only access. */
 	public static final String Write = "write";
 
-	/**
-	 * Allow truncate.
-	 */
+	/** Role name for truncate. */
 	public static final String Truncate = "truncate";
 
-	/**
-	 * Manage data masking.
-	 */
+	/** Role name for data masking administration. */
 	public static final String MaskingAdmin = "masking-admin";
 
-	/**
-	 * Allow read masked data.
-	 */
+	/** Role name for read masked data. */
 	public static final String ReadMasked = "read-masked";
 
-	/**
-	 * Allow write masked data.
-	 */
+	/** Role name for write masked data. */
 	public static final String WriteMasked = "write-masked";
 
-	/**
-	 * Role name.
-	 */
+	/** Role name. */
 	public String name;
 
-	/**
-	 * List of assigned privileges.
-	 */
+	/** Assigned privileges (namespace/set-scoped when applicable). */
 	public List<Privilege> privileges;
 
-	/**
-	 * List of allowable IP addresses.
-	 */
+	/** Allowed IP addresses (whitelist); null or empty for no restriction. */
 	public List<String> whitelist;
 
-	/**
-	 * Maximum reads per second limit.
-	 */
+	/** Maximum reads per second (0 for no limit). */
 	public int readQuota;
 
-	/**
-	 * Maximum writes per second limit.
-	 */
+	/** Maximum writes per second (0 for no limit). */
 	public int writeQuota;
 
 	public String toString() {
diff --git a/client/src/com/aerospike/client/admin/User.java b/client/src/com/aerospike/client/admin/User.java
index a5ebdf213..b8ca3b634 100644
--- a/client/src/com/aerospike/client/admin/User.java
+++ b/client/src/com/aerospike/client/admin/User.java
@@ -19,48 +19,48 @@
 import java.util.List;
 
 /**
- * User and assigned roles.
+ * User record: name, assigned roles, optional read/write stats and connection count. Returned by {@link com.aerospike.client.AerospikeClient#queryUser} and in the list from {@link com.aerospike.client.AerospikeClient#queryUsers}.
+ * <p>
+ * {@link #readInfo} and {@link #writeInfo} are server-defined statistic lists (e.g. quota, TPS, RPS); offsets may change in future server versions.
+ *
+ * <p><b>Example:</b>
+ * <p>Query a user and read name and roles.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * try {
+ *   User user = client.queryUser(null, "jdoe");
+ *   if (user != null) {
+ *     String name = user.name;
+ *     List roles = user.roles;
+ *   }
+ * } finally {
+ *   client.close();
+ * }
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient#queryUser
+ * @see com.aerospike.client.AerospikeClient#queryUsers
+ * @see com.aerospike.client.AerospikeClient#createUser
+ * @see Role
  */
 public final class User {
-	/**
-	 * User name.
-	 */
+	/** User name. */
 	public String name;
 
-	/**
-	 * List of assigned roles.
-	 */
+	/** Assigned role names. */
 	public List<String> roles;
 
 	/**
-	 * List of read statistics. List may be null.
-	 * Current statistics by offset are:
-	 * <ul>
-	 * <li>0: read quota in records per second</li>
-	 * <li>1: single record read transaction rate (TPS)</li>
-	 * <li>2: read scan/query record per second rate (RPS)</li>
-	 * <li>3: number of limitless read scans/queries</li>
-	 * </ul>
-	 * Future server releases may add additional statistics.
+	 * Read statistics (may be null). Current offsets: 0 = read quota (RPS), 1 = read TPS, 2 = read scan/query RPS, 3 = limitless read scans/queries. Future server versions may add more.
 	 */
 	public List<Integer> readInfo;
 
 	/**
-	 * List of write statistics. List may be null.
-	 * Current statistics by offset are:
-	 * <ul>
-	 * <li>0: write quota in records per second</li>
-	 * <li>1: single record write transaction rate (TPS)</li>
-	 * <li>2: write scan/query record per second rate (RPS)</li>
-	 * <li>3: number of limitless write scans/queries</li>
-	 * </ul>
-	 * Future server releases may add additional statistics.
+	 * Write statistics (may be null). Current offsets: 0 = write quota (RPS), 1 = write TPS, 2 = write scan/query RPS, 3 = limitless write scans/queries. Future server versions may add more.
 	 */
 	public List<Integer> writeInfo;
 
-	/**
-	 * Number of currently open connections.
-	 */
+	/** Number of currently open connections for this user. */
 	public int connsInUse;
 
 	public String toString() {
diff --git a/client/src/com/aerospike/client/async/AsyncIndexTask.java b/client/src/com/aerospike/client/async/AsyncIndexTask.java
index 3df5ecb36..48a298581 100644
--- a/client/src/com/aerospike/client/async/AsyncIndexTask.java
+++ b/client/src/com/aerospike/client/async/AsyncIndexTask.java
@@ -29,7 +29,28 @@
 import com.aerospike.client.policy.InfoPolicy;
 
 /**
- * Async index task monitor.
+ * Asynchronous index task returned from {@link IAerospikeClient#createIndex} (and drop) to poll completion.
+ * <p>
+ * Use {@link #queryStatus(EventLoop, InfoPolicy, Node, TaskStatusListener)} to check a node; all nodes must report 100% load for the task to be done.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * InfoPolicy policy = new InfoPolicy();
+ * Node node = client.getNodes()[0];
+ *
+ * client.createIndex(loop, policy, "ns", "set", "idx1", "bin1", IndexType.STRING, new IndexListener() {
+ *   public void onSuccess(AsyncIndexTask task) {
+ *     task.queryStatus(loop, policy, node, new TaskStatusListener() { ... });
+ *   }
+ *   public void onFailure(AerospikeException e) { }
+ * });
+ * }</pre>
+ *
+ * @see IAerospikeClient#createIndex
+ * @see com.aerospike.client.listener.TaskStatusListener
  */
 public class AsyncIndexTask {
 	private final IAerospikeClient client;
@@ -38,7 +59,10 @@ public class AsyncIndexTask {
 	private final boolean isCreate;
 
 	/**
-	 * Initialize task with fields needed to query server nodes.
+	 * @param client client (must not be null)
+	 * @param namespace namespace
+	 * @param indexName index name
+	 * @param isCreate true for create, false for drop
 	 */
 	public AsyncIndexTask(IAerospikeClient client, String namespace, String indexName, boolean isCreate) {
 		this.client = client;
@@ -48,8 +72,11 @@ public AsyncIndexTask(IAerospikeClient client, String namespace, String indexNam
 	}
 
 	/**
-	 * Asynchronously query node for task completion status.
-	 * All nodes must respond with load_pct of 100 to be considered done.
+	 * Asynchronously queries the given node for this task's completion status; all nodes must report load_pct 100 for the task to be done.
+	 * @param eventLoop event loop to run the request on (must not be null)
+	 * @param policy info policy (must not be null)
+	 * @param node node to query (must not be null)
+	 * @param listener callback for status or failure (must not be null)
 	 */
 	public void queryStatus(EventLoop eventLoop, InfoPolicy policy, Node node, TaskStatusListener listener) {
 		if (client.getNodes().length == 0) {
diff --git a/client/src/com/aerospike/client/async/EventLoop.java b/client/src/com/aerospike/client/async/EventLoop.java
index b619a3fb8..f896f1bfe 100644
--- a/client/src/com/aerospike/client/async/EventLoop.java
+++ b/client/src/com/aerospike/client/async/EventLoop.java
@@ -22,77 +22,87 @@
 import com.aerospike.client.cluster.Node;
 
 /**
- * Aerospike event loop interface.
+ * Single event loop used to run asynchronous Aerospike operations.
+ * <p>
+ * Obtain an event loop from {@link EventLoops#next()} or {@link EventLoops#get(int)} and pass it
+ * to async client methods (e.g. {@link com.aerospike.client.IAerospikeClient#get}).
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * client.get(loop, new Policy(), new RecordListener() { ... }, key);
+ * }</pre>
+ *
+ * @see EventLoops
+ * @see NioEventLoop
+ * @see NettyEventLoop
  */
 public interface EventLoop {
 	/**
-	 * Execute async command.  Execute immediately if in event loop.
-	 * Otherwise, place command on event loop queue.
+	 * Executes an async command on this event loop; runs immediately if called from the event loop thread, otherwise enqueues.
+	 * @param cluster cluster (must not be null)
+	 * @param command command to run (must not be null)
 	 */
 	public void execute(Cluster cluster, AsyncCommand command);
 
 	/**
-	 * Schedule execution of runnable command on event loop.
-	 * Command is placed on event loop queue and is never executed directly.
+	 * Schedules a runnable on this event loop; always enqueues and never runs in the caller thread.
+	 * @param command runnable to run (must not be null)
 	 */
 	public void execute(Runnable command);
 
-	/**
-	 * Retry async batch command.  For internal use only.
-	 */
+	/** Retry async batch command. For internal use only. */
 	public void executeBatchRetry(Runnable other, AsyncCommand command, long deadline);
 
 	/**
-	 * Schedule execution of runnable command with delay.
+	 * Schedules a runnable to run after the given delay.
+	 * @param command runnable to run (must not be null)
+	 * @param delay delay amount
+	 * @param unit unit of delay (must not be null)
 	 */
 	public void schedule(Runnable command, long delay, TimeUnit unit);
 
 	/**
-	 * Schedule execution with a reusable ScheduleTask.
+	 * Schedules a reusable task to run after the given delay.
+	 * @param task task to run (must not be null)
+	 * @param delay delay amount
+	 * @param unit unit of delay (must not be null)
 	 */
 	public void schedule(ScheduleTask task, long delay, TimeUnit unit);
 
 	/**
-	 * Create async connector command.
+	 * Creates an async connector command for the given cluster and node.
+	 * @param cluster cluster (must not be null)
+	 * @param node node (must not be null)
+	 * @param listener listener (must not be null)
+	 * @return new connector command
 	 */
 	public AsyncConnector createConnector(Cluster cluster, Node node, AsyncConnector.Listener listener);
 
-	/**
-	 * Return the approximate number of commands currently being processed on
-	 * the event loop.  The value is approximate because the call may be from a
-	 * different thread than the event loop’s thread and there are no locks or
-	 * atomics used.
-	 *
-	 * If accuracy is important and not running in the event loop thread,
-	 * the slower execute(Runnable) can be called to run this method in the
-	 * event loop thread.
+/**
+	 * Approximate number of commands currently being processed on this event loop.
+	 * <p>
+	 * Value is approximate when called from a different thread. For accuracy from another thread, run this inside {@link #execute(Runnable)} on this event loop.
+	 * @return approximate process size (non-negative)
 	 */
 	public int getProcessSize();
 
 	/**
-	 * Return the approximate number of commands stored on this event loop's
-	 * delay queue that have not been started yet.  The value is approximate
-	 * because the call may be from a different thread than the event loop’s
-	 * thread and there are no locks or atomics used.
-	 *
-	 * If accuracy is important and not running in the event loop thread,
-	 * the slower execute(Runnable) can be called to run this method in the
-	 * event loop thread.
+	 * Approximate number of commands on this event loop's delay queue not yet started.
+	 * <p>
+	 * Value is approximate when called from a different thread. For accuracy from another thread, run this inside {@link #execute(Runnable)} on this event loop.
+	 * @return approximate queue size (non-negative)
 	 */
 	public int getQueueSize();
 
-	/**
-	 * Return event loop array index.
-	 */
+	/** @return this event loop's index in its {@link EventLoops} array */
 	public int getIndex();
 
-	/**
-	 * Is current thread the event loop thread.
-=	 */
+	/** @return true if the current thread is this event loop's thread */
 	public boolean inEventLoop();
 
-	/**
-	 * For internal use only.
-	 */
+	/** For internal use only. */
 	public EventState createState();
 }
diff --git a/client/src/com/aerospike/client/async/EventLoopStats.java b/client/src/com/aerospike/client/async/EventLoopStats.java
index 4f8997c54..66b8ab67b 100644
--- a/client/src/com/aerospike/client/async/EventLoopStats.java
+++ b/client/src/com/aerospike/client/async/EventLoopStats.java
@@ -17,32 +17,32 @@
 package com.aerospike.client.async;
 
 /**
- * Event loop statistics.
+ * Snapshot of a single event loop's load (process and queue sizes).
+ * <p>
+ * Used in {@link com.aerospike.client.cluster.ClusterStats#eventLoops}; obtain via {@link com.aerospike.client.AerospikeClient#getClusterStats()}.
+ *
+ * @see com.aerospike.client.cluster.ClusterStats
+ * @see EventLoop#getProcessSize
+ * @see EventLoop#getQueueSize
  */
 public final class EventLoopStats {
-	/**
-	 * Approximate number of commands actively being processed on
-	 * the event loop.
-	 */
+	/** Approximate number of commands actively being processed on the event loop. */
 	public final int processSize;
 
-	/**
-	 * Approximate number of commands stored on this event loop's
-	 * delay queue that have not been started yet.
-	 */
+	/** Approximate number of commands on the event loop's delay queue not yet started. */
 	public final int queueSize;
 
 	/**
-	 * Event loop statistics constructor.
+	 * Builds stats from the given event loop (values are snapshots at construction time).
+	 * @param eventLoop event loop (must not be null)
 	 */
 	public EventLoopStats(EventLoop eventLoop) {
 		this.processSize = eventLoop.getProcessSize();
 		this.queueSize = eventLoop.getQueueSize();
 	}
 
-	/**
-	 * Convert statistics to string.
-	 */
+	/** @return processSize and queueSize as a comma-separated string */
+	@Override
 	public String toString() {
 		return "" + processSize + ',' + queueSize;
 	}
diff --git a/client/src/com/aerospike/client/async/EventLoopType.java b/client/src/com/aerospike/client/async/EventLoopType.java
index f2073b7e4..ae4fdf63a 100644
--- a/client/src/com/aerospike/client/async/EventLoopType.java
+++ b/client/src/com/aerospike/client/async/EventLoopType.java
@@ -17,31 +17,25 @@
 package com.aerospike.client.async;
 
 /**
- * Type of async event loop used.
+ * Type of async event loop implementation (Netty or direct NIO).
+ * <p>
+ * Used when constructing {@link NettyEventLoops} with an explicit type; otherwise the type is inferred from the Netty {@link io.netty.channel.EventLoopGroup}.
+ *
+ * @see NettyEventLoops
  */
 public enum EventLoopType {
-	/**
-	 * Direct NIO
-	 */
+	/** Direct NIO (used by {@link NioEventLoops}). */
 	DIRECT_NIO,
 
-	/**
-	 * Netty NIO
-	 */
+	/** Netty NIO. */
 	NETTY_NIO,
 
-	/**
-	 * Netty epoll. Available on Linux.
-	 */
+	/** Netty epoll; available on Linux. */
 	NETTY_EPOLL,
 
-	/**
-	 * Netty kqueue. Available on MacOS, FreeBSD.
-	 */
+	/** Netty kqueue; available on MacOS, FreeBSD. */
 	NETTY_KQUEUE,
 
-	/**
-	 * Netty io_uring. Available on Linux.
-	 */
+	/** Netty io_uring; available on Linux. */
 	NETTY_IOURING
 }
diff --git a/client/src/com/aerospike/client/async/EventLoops.java b/client/src/com/aerospike/client/async/EventLoops.java
index a2741122c..18d71790a 100644
--- a/client/src/com/aerospike/client/async/EventLoops.java
+++ b/client/src/com/aerospike/client/async/EventLoops.java
@@ -19,34 +19,41 @@
 import java.io.Closeable;
 
 /**
- * Aerospike event loops interface.
+ * Group of event loops used for asynchronous Aerospike operations.
+ * <p>
+ * Set on {@link com.aerospike.client.policy.ClientPolicy#eventLoops} when constructing the client, or obtain from {@link com.aerospike.client.AerospikeClient#getEventLoops()}. Use {@link #next()} or {@link #get(int)} to get an event loop for async API calls.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * }</pre>
+ *
+ * @see EventLoop
+ * @see NioEventLoops
+ * @see NettyEventLoops
+ * @see com.aerospike.client.policy.ClientPolicy#eventLoops
  */
 public interface EventLoops extends Closeable {
-	/**
-	 * Return array of Aerospike event loops.
-	 */
+	/** @return array of all event loops in this group (must not be null) */
 	public EventLoop[] getArray();
 
-	/**
-	 * Return number of event loops in this group.
-	 */
+	/** @return number of event loops in this group */
 	public int getSize();
 
 	/**
-	 * Return Aerospike event loop given array index..
+	 * @param index index in the event loop array (0 to size-1)
+	 * @return the event loop at the given index
 	 */
 	public EventLoop get(int index);
 
 	/**
-	 * Return next Aerospike event loop in round-robin fashion.
-	 * Implementations might not use an atomic sequence counter.
-	 * Non-atomic counters improve performance, but might result
-	 * in a slightly imperfect round-robin distribution.
+	 * Returns the next event loop in round-robin order; implementations may use a non-atomic counter for performance.
+	 * @return next event loop (must not be null)
 	 */
 	public EventLoop next();
 
-	/**
-	 * Close event loops.
-	 */
+	/** Closes this event loop group and releases resources. */
 	public void close();
 }
diff --git a/client/src/com/aerospike/client/async/EventPolicy.java b/client/src/com/aerospike/client/async/EventPolicy.java
index 7971cd5cb..80d3b6217 100644
--- a/client/src/com/aerospike/client/async/EventPolicy.java
+++ b/client/src/com/aerospike/client/async/EventPolicy.java
@@ -17,7 +17,18 @@
 package com.aerospike.client.async;
 
 /**
- * Asynchronous event loop configuration.
+ * Configuration for asynchronous event loops (limits, timeouts, queue capacities).
+ * <p>
+ * Pass to {@link NioEventLoops} or {@link NettyEventLoops} constructors. Defaults are suitable for most cases; tune when limiting concurrent commands or memory.
+ * <pre>{@code
+ * EventPolicy policy = new EventPolicy();
+ * policy.maxCommandsInProcess = 40;
+ * EventLoops eventLoops = new NioEventLoops(policy, 4);
+ * }</pre>
+ *
+ * @see NioEventLoops
+ * @see NettyEventLoops
+ * @see com.aerospike.client.AerospikeException.AsyncQueueFull
  */
 public final class EventPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/async/NettyEventLoops.java b/client/src/com/aerospike/client/async/NettyEventLoops.java
index 8cfc996a6..fcfa44eee 100644
--- a/client/src/com/aerospike/client/async/NettyEventLoops.java
+++ b/client/src/com/aerospike/client/async/NettyEventLoops.java
@@ -36,8 +36,22 @@
 import io.netty.util.concurrent.EventExecutor;
 
 /**
- * Aerospike wrapper around netty event loops.
- * Implements the Aerospike EventLoops interface.
+ * Netty-based implementation of {@link EventLoops} (wraps an existing Netty {@link io.netty.channel.EventLoopGroup}).
+ * <p>
+ * Use when the application already uses Netty; create from your {@link io.netty.channel.EventLoopGroup} and set on {@link com.aerospike.client.policy.ClientPolicy#eventLoops}.
+ * <pre>{@code
+ * EventLoopGroup group = new NioEventLoopGroup(4);
+ * EventLoops eventLoops = new NettyEventLoops(group);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * }</pre>
+ *
+ * @see EventLoops
+ * @see NioEventLoops
+ * @see EventPolicy
+ * @see EventLoopType
+ * @see com.aerospike.client.policy.ClientPolicy#eventLoops
  */
 public final class NettyEventLoops implements EventLoops {
 
@@ -47,23 +61,27 @@ public final class NettyEventLoops implements EventLoops {
 	final EventLoopType eventLoopType;
 	private int eventIter;
 
-	/**
-	 * Create Aerospike event loop wrappers from given netty event loops.
-	 */
+	/** Creates Aerospike event loop wrappers from the given Netty event loop group (type inferred). */
 	public NettyEventLoops(EventLoopGroup group) {
 		this(new EventPolicy(), group);
 	}
 
 	/**
-	 * Create Aerospike event loop wrappers from given netty event loops.
-	 * The type of event loop is determined from the event loop group instance.
+	 * Creates Aerospike event loop wrappers from the given Netty group and policy; type is inferred from the group.
+	 * @param policy event loop policy (must not be null)
+	 * @param group Netty event loop group (must not be null)
+	 * @throws com.aerospike.client.AerospikeException when minTimeout is invalid
 	 */
 	public NettyEventLoops(EventPolicy policy, EventLoopGroup group) {
 		this(policy, group, getEventLoopType(group));
 	}
 
 	/**
-	 * Create Aerospike event loop wrappers from given netty event loops and specified event loop type.
+	 * Creates Aerospike event loop wrappers with an explicit event loop type.
+	 * @param policy event loop policy (must not be null)
+	 * @param group Netty event loop group (must not be null)
+	 * @param type event loop type (must not be null)
+	 * @throws com.aerospike.client.AerospikeException when minTimeout is invalid
 	 */
 	public NettyEventLoops(EventPolicy policy, EventLoopGroup group, EventLoopType type) {
 		if (policy.minTimeout < 5) {
diff --git a/client/src/com/aerospike/client/async/NettyTlsContext.java b/client/src/com/aerospike/client/async/NettyTlsContext.java
index a6c64068f..e4f453bd9 100644
--- a/client/src/com/aerospike/client/async/NettyTlsContext.java
+++ b/client/src/com/aerospike/client/async/NettyTlsContext.java
@@ -38,14 +38,27 @@
 import io.netty.handler.ssl.SslHandler;
 
 /**
- * Netty SslContext container.
+ * Netty SslContext container for TLS when using Netty-based event loops.
+ * <p>
+ * Optionally set on {@link com.aerospike.client.policy.TlsPolicy#nettyContext} to share one TLS context across multiple {@link com.aerospike.client.AerospikeClient} instances that use Netty.
+ * <pre>{@code
+ * TlsPolicy tp = new TlsPolicy();
+ * tp.nettyContext = new NettyTlsContext(tp);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.tlsPolicy = tp;
+ * policy.eventLoops = new NettyEventLoops(...);
+ * }</pre>
+ *
+ * @see com.aerospike.client.policy.TlsPolicy#nettyContext
  */
 public final class NettyTlsContext implements CipherSuiteFilter {
 	private final TlsPolicy policy;
 	private final SslContext context;
 
 	/**
-	 * Construct Netty SslContext.
+	 * Builds a Netty SslContext from the given TLS policy.
+	 * @param policy TLS policy (must not be null)
+	 * @throws com.aerospike.client.AerospikeException when Netty TLS initialization fails
 	 */
 	public NettyTlsContext(TlsPolicy policy) {
 		this.policy = policy;
@@ -94,15 +107,15 @@ public NettyTlsContext(TlsPolicy policy) {
 	}
 
 	/**
-	 * Create TLS handler.
+	 * Creates a TLS handler for the given Netty channel.
+	 * @param ch Netty socket channel (must not be null)
+	 * @return new SslHandler for the channel
 	 */
 	public SslHandler createHandler(SocketChannel ch) {
 		return context.newHandler(ch.alloc());
 	}
 
-	/**
-	 * Return supported ciphers.
-	 */
+	/** @return supported ciphers per policy, or default from context when policy ciphers are null */
 	@Override
 	public String[] filterCipherSuites(Iterable<String> ciphers, List<String> defaultCiphers, Set<String> supportedCiphers) {
 		if (policy.ciphers != null) {
diff --git a/client/src/com/aerospike/client/async/NioEventLoops.java b/client/src/com/aerospike/client/async/NioEventLoops.java
index 9cb22dba0..6b897edac 100644
--- a/client/src/com/aerospike/client/async/NioEventLoops.java
+++ b/client/src/com/aerospike/client/async/NioEventLoops.java
@@ -23,46 +23,57 @@
 import com.aerospike.client.util.Util;
 
 /**
- * Asynchronous event loops.
+ * Direct NIO implementation of {@link EventLoops} (no Netty dependency).
+ * <p>
+ * Create and set on {@link com.aerospike.client.policy.ClientPolicy#eventLoops} before constructing the client. Use one event loop per CPU core by default, or pass an explicit size.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * }</pre>
+ *
+ * @see EventLoops
+ * @see NettyEventLoops
+ * @see EventPolicy
+ * @see com.aerospike.client.policy.ClientPolicy#eventLoops
  */
 public final class NioEventLoops implements EventLoops {
 
 	final NioEventLoop[] eventLoops;
 	private int eventIter;
 
-	/**
-	 * Create direct NIO event loops, one per CPU core.
-	 */
+	/** Creates direct NIO event loops, one per CPU core. */
 	public NioEventLoops() throws AerospikeException {
 		this(0);
 	}
 
 	/**
-	 * Create direct NIO event loops.
-	 *
-	 * @param size		number of event loops to create
+	 * Creates direct NIO event loops.
+	 * @param size number of event loops (0 for one per CPU core)
+	 * @throws com.aerospike.client.AerospikeException when minTimeout is invalid or creation fails
 	 */
 	public NioEventLoops(int size) throws AerospikeException {
 		this(new EventPolicy(), size);
 	}
 
 	/**
-	 * Create direct NIO event loops.
-	 *
-	 * @param policy	event loop policy
-	 * @param size		number of event loops to create
+	 * Creates direct NIO event loops with the given policy.
+	 * @param policy event loop policy (must not be null)
+	 * @param size number of event loops (0 for one per CPU core)
+	 * @throws com.aerospike.client.AerospikeException when minTimeout is invalid or creation fails
 	 */
 	public NioEventLoops(EventPolicy policy, int size) throws AerospikeException {
 		this(policy, size, false, "aerospike-nio-event-loop");
 	}
 
 	/**
-	 * Create direct NIO event loops.
-	 *
-	 * @param policy	event loop policy
-	 * @param size		number of event loops to create
-	 * @param daemon	true if the associated threads should run as a daemons
-	 * @param poolName	event loop thread pool name
+	 * Creates direct NIO event loops with the given policy and thread settings.
+	 * @param policy event loop policy (must not be null)
+	 * @param size number of event loops (0 for one per CPU core)
+	 * @param daemon true if event loop threads should be daemon threads
+	 * @param poolName name for the event loop thread pool
+	 * @throws com.aerospike.client.AerospikeException when minTimeout is invalid or creation fails
 	 */
 	public NioEventLoops(EventPolicy policy, int size, boolean daemon, String poolName) throws AerospikeException {
 		if (policy.minTimeout < 5) {
diff --git a/client/src/com/aerospike/client/cdt/CTX.java b/client/src/com/aerospike/client/cdt/CTX.java
index 88e772d6f..0cb2e494d 100644
--- a/client/src/com/aerospike/client/cdt/CTX.java
+++ b/client/src/com/aerospike/client/cdt/CTX.java
@@ -27,9 +27,31 @@
 import com.aerospike.client.util.Unpacker;
 
 /**
- * Nested CDT context.  Identifies the location of nested list/map to apply the operation.
- * for the current level.  An array of CTX identifies location of the list/map on multiple
- * levels on nesting.
+ * Nested CDT context. Identifies the path to a nested list or map for an operation or query.
+ * <p>
+ * An array of CTX identifies location of the list/map on multiple levels on nesting.
+ * <p>Build nested path with CTX for operate and index creation.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * // Nested path: map "book" then all list items (e.g. for CdtOperation.selectByPath)
+ * CTX ctx1 = CTX.mapKey(Value.get("book"));
+ * CTX ctx2 = CTX.allChildren();
+ *
+ * // List index -1 = last element (e.g. for Filter.range on list bin)
+ * CTX listCtx = CTX.listIndex(-1);
+ * Filter.range("listbin", 10, 20, listCtx);
+ *
+ * // Query index on last element of list
+ * IndexTask task = client.createIndex(null, "ns", "set", "idx1", "listbin",
+ *     IndexType.NUMERIC, IndexCollectionType.DEFAULT, CTX.listRank(-1));
+ * }</pre>
+ *
+ * @see com.aerospike.client.cdt.CdtOperation
+ * @see com.aerospike.client.cdt.ListOperation
+ * @see com.aerospike.client.cdt.MapOperation
+ * @see com.aerospike.client.query.Filter#range
  */
 public final class CTX {
 	/**
diff --git a/client/src/com/aerospike/client/cdt/CdtOperation.java b/client/src/com/aerospike/client/cdt/CdtOperation.java
index ab2b5f98a..87190645f 100644
--- a/client/src/com/aerospike/client/cdt/CdtOperation.java
+++ b/client/src/com/aerospike/client/cdt/CdtOperation.java
@@ -26,7 +26,34 @@
 import com.aerospike.client.util.Packer;
 import com.aerospike.client.exp.Expression;
 
-public class CdtOperation {	
+/**
+ * CDT select and apply operations on nested list/map bins by path (context).
+ * <p>
+ * Use with {@link com.aerospike.client.AerospikeClient#operate} to select values or apply expressions inside nested CDTs. Build context with {@link CTX#mapKey}, {@link CTX#listIndex}, {@link CTX#allChildren}, {@link CTX#allChildrenWithFilter}, etc.
+ * <p>Select and modify nested CDT values by path with CTX.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * Map rootMap = new HashMap();
+ * rootMap.put("book", booksList);
+ * client.put(null, key, new Bin("bin", rootMap));
+ *
+ * CTX ctx1 = CTX.mapKey(Value.get("book"));
+ * CTX ctx2 = CTX.allChildren();
+ * Operation selectOp = CdtOperation.selectByPath("bin", Exp.SELECT_VALUE, ctx1, ctx2);
+ * Record rec = client.operate(null, key, selectOp);
+ * List results = rec.getList("bin");
+ *
+ * Expression modifyExp = Exp.build(Exp.mul(Exp.floatLoopVar(LoopVarPart.VALUE), Exp.val(1.10)));
+ * Operation applyOp = CdtOperation.modifyByPath("bin", Exp.MODIFY_DEFAULT, modifyExp, ctx1, ctx2, CTX.mapKey(Value.get("price")));
+ * client.operate(null, key, applyOp);
+ * }</pre>
+ *
+ * @see CTX
+ * @see com.aerospike.client.exp.Exp
+ * @see com.aerospike.client.AerospikeClient#operate
+ */
+public class CdtOperation {
     /**
      * Create CDT select operation with context.
      *
diff --git a/client/src/com/aerospike/client/cdt/ListOperation.java b/client/src/com/aerospike/client/cdt/ListOperation.java
index 3b11869c7..338bb166e 100644
--- a/client/src/com/aerospike/client/cdt/ListOperation.java
+++ b/client/src/com/aerospike/client/cdt/ListOperation.java
@@ -24,34 +24,54 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * List bin operations. Create list operations used by client operate command.
+ * List bin operations for the client operate command. List operations support negative indexing.
+ * Index out of bounds returns a parameter error; a range partially out of bounds returns the valid
+ * part. Use optional {@link CTX} for nested list/map paths. Prefer {@link #appendItems} over
+ * multiple {@link #append} for better performance.
  * <p>
- * List operations support negative indexing.  If the index is negative, the
- * resolved index starts backwards from end of list. If an index is out of bounds,
- * a parameter error will be returned. If a range is partially out of bounds, the
- * valid part of the range will be returned. Index/Range examples:
+ * Index (item offset from start; negative = from end):
  * <ul>
- * <li>Index 0: First item in list.</li>
- * <li>Index 4: Fifth item in list.</li>
- * <li>Index -1: Last item in list.</li>
- * <li>Index -3: Third to last item in list.</li>
- * <li>Index 1 Count 2: Second and third items in list.</li>
- * <li>Index -3 Count 3: Last three items in list.</li>
- * <li>Index -5 Count 4: Range between fifth to last item to second to last item inclusive.</li>
- * </ul>
- * <p>
- * Nested CDT operations are supported by optional CTX context arguments.  Examples:
- * <ul>
- * <li>bin = [[7,9,5],[1,2,3],[6,5,4,1]]</li>
- * <li>Append 11 to last list.</li>
- * <li>ListOperation.append("bin", Value.get(11), CTX.listIndex(-1))</li>
- * <li>bin result = [[7,9,5],[1,2,3],[6,5,4,1,11]]</li>
- * <li></li>
- * <li>bin = {key1=[[7,9,5],[13]], key2=[[9],[2,4],[6,1,9]], key3=[[6,5]]}</li>
- * <li>Append 11 to lowest ranked list in map identified by "key2".</li>
- * <li>ListOperation.append("bin", Value.get(11), CTX.mapKey(Value.get("key2")), CTX.listRank(0))</li>
- * <li>bin result = {key1=[[7,9,5],[13]], key2=[[9],[2,4,11],[6,1,9]], key3=[[6,5]]}</li>
+ * <li>Index 0: first item; 4: fifth item; -1: last item; -3: third to last.</li>
+ * <li>Index 1 Count 2: second and third items; Index -3 Count 3: last three items.</li>
+ * <li>Index -5 Count 4: range from fifth-to-last to second-to-last inclusive.</li>
  * </ul>
+ * <p>Append, pop, size, appendItems, getRange; get by index/range; nested append with CTX.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "listkey");
+ * client.delete(null, key);
+ *
+ * Record rec = client.operate(null, key,
+ *     ListOperation.append("bin", Value.get(55)),
+ *     ListOperation.append("bin", Value.get(77)),
+ *     ListOperation.pop("bin", -1),
+ *     ListOperation.size("bin"));
+ * long size = (Long) rec.getList("bin").get(3);
+ *
+ * List itemList = new ArrayList<>();
+ * itemList.add(Value.get(12));
+ * itemList.add(Value.get("my string"));
+ * client.operate(null, key, ListOperation.appendItems("bin", itemList));
+ * rec = client.operate(null, key, ListOperation.getRange("bin", 0, 4));
+ * List range = (List) rec.getList("bin").get(0);
+ *
+ * // Index/range: get by index 0 or -1, range (1, 2), last three (-3, 3), -5 count 4
+ * client.operate(null, key, ListOperation.getByIndex("bin", 0, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndex("bin", -1, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndexRange("bin", 1, 2, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndexRange("bin", -3, 3, ListReturnType.VALUE));
+ * client.operate(null, key, ListOperation.getByIndexRange("bin", -5, 4, ListReturnType.VALUE));
+ *
+ * // Nested: append 11 to last list (bin = [[7,9,5],[1,2,3],[6,5,4,1]] -> last list gets 11)
+ * client.operate(null, key, ListOperation.append("bin", Value.get(11), CTX.listIndex(-1)));
+ * // Nested with map: append 11 to lowest-ranked list in map "key2"
+ * client.operate(null, key, ListOperation.append("bin", Value.get(11), CTX.mapKey(Value.get("key2")), CTX.listRank(0)));
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see CTX
+ * @see ListPolicy
+ * @see ListReturnType
  */
 public class ListOperation {
 	private static final int SET_TYPE = 0;
diff --git a/client/src/com/aerospike/client/cdt/ListOrder.java b/client/src/com/aerospike/client/cdt/ListOrder.java
index 43c223f8e..593eaa554 100644
--- a/client/src/com/aerospike/client/cdt/ListOrder.java
+++ b/client/src/com/aerospike/client/cdt/ListOrder.java
@@ -17,7 +17,12 @@
 package com.aerospike.client.cdt;
 
 /**
- * List storage order.
+ * List storage order; used in {@link ListPolicy} and {@link ListOperation#create}.
+ * <p>
+ * Use {@link #ORDERED} when you need rank/getByRank; default is {@link #UNORDERED}.
+ *
+ * @see ListPolicy
+ * @see ListOperation
  */
 public enum ListOrder {
 	/**
diff --git a/client/src/com/aerospike/client/cdt/ListPolicy.java b/client/src/com/aerospike/client/cdt/ListPolicy.java
index d98f68660..53fc40350 100644
--- a/client/src/com/aerospike/client/cdt/ListPolicy.java
+++ b/client/src/com/aerospike/client/cdt/ListPolicy.java
@@ -17,12 +17,24 @@
 package com.aerospike.client.cdt;
 
 /**
- * List policy directives when creating a list and writing list items.
+ * List policy: order and write flags when creating a list or writing list items.
+ * <p>
+ * Use with {@link ListOperation#create}, {@link ListOperation#append}, {@link ListOperation#appendItems}, {@link ListOperation#increment}, etc. when the list may not exist or when you need ordered/unique semantics.
+ * <p>Use list policy with appendItems and increment.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * ListPolicy unordered = ListPolicy.Default;
+ * ListPolicy ordered = new ListPolicy(ListOrder.ORDERED, ListWriteFlags.DEFAULT);
+ * client.operate(null, key, ListOperation.appendItems(ordered, "bin", itemList));
+ * client.operate(null, key, ListOperation.increment(ordered, "bin", 0, Value.get(1)));
+ * }</pre>
+ *
+ * @see ListOperation
+ * @see ListOrder
+ * @see ListWriteFlags
  */
 public final class ListPolicy {
-	/**
-	 * Default unordered list with normal write semantics.
-	 */
+	/** Default unordered list with normal write semantics. */
 	public static final ListPolicy Default = new ListPolicy();
 
 	public final int attributes;
diff --git a/client/src/com/aerospike/client/cdt/ListReturnType.java b/client/src/com/aerospike/client/cdt/ListReturnType.java
index 6b764d591..18497061c 100644
--- a/client/src/com/aerospike/client/cdt/ListReturnType.java
+++ b/client/src/com/aerospike/client/cdt/ListReturnType.java
@@ -17,7 +17,17 @@
 package com.aerospike.client.cdt;
 
 /**
- * List return type. Type of data to return when selecting or removing items from the list.
+ * What to return from list read/remove operations (index, rank, value, count, etc.).
+ * <p>
+ * Pass to {@link ListOperation#get}, {@link ListOperation#getByIndex}, {@link ListOperation#getByRank}, {@link ListOperation#getRange}, {@link ListOperation#removeByValue}, and similar.
+ * <p>Use ListReturnType in getByIndex and getByValue.</p>
+ * <pre>{@code
+ * Record rec = client.operate(null, key,
+ *     ListOperation.getByIndex("bin", 0, ListReturnType.VALUE),
+ *     ListOperation.getByValue("bin", Value.get(5), ListReturnType.INDEX));
+ * }</pre>
+ *
+ * @see ListOperation
  */
 public final class ListReturnType {
 	/**
diff --git a/client/src/com/aerospike/client/cdt/ListWriteFlags.java b/client/src/com/aerospike/client/cdt/ListWriteFlags.java
index 5680e63ff..53c17328e 100644
--- a/client/src/com/aerospike/client/cdt/ListWriteFlags.java
+++ b/client/src/com/aerospike/client/cdt/ListWriteFlags.java
@@ -17,11 +17,15 @@
 package com.aerospike.client.cdt;
 
 /**
- * List write bit flags. Use BITWISE OR to combine flags. Example:
- * 
- * <pre>{@code 
+ * List write bit flags; combine with BITWISE OR and pass to {@link ListPolicy}.
+ * <p>
+ * <p>Combine list write flags and pass to ListPolicy.</p>
+ * <pre>{@code
  * int flags = ListWriteFlags.ADD_UNIQUE | ListWriteFlags.NO_FAIL | ListWriteFlags.PARTIAL;
+ * ListPolicy policy = new ListPolicy(ListOrder.ORDERED, flags);
  * }</pre>
+ *
+ * @see ListPolicy
  */
 public final class ListWriteFlags {
 	/**
diff --git a/client/src/com/aerospike/client/cdt/MapOperation.java b/client/src/com/aerospike/client/cdt/MapOperation.java
index 32557138f..a71655a6e 100644
--- a/client/src/com/aerospike/client/cdt/MapOperation.java
+++ b/client/src/com/aerospike/client/cdt/MapOperation.java
@@ -25,53 +25,58 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Map bin operations. Create map operations used by the client operate command.
- * The default unique key map is unordered. Valid map key types are:
- * <ul>
- * <li>String</li>
- * <li>Integer</li>
- * <li>byte[]</li>
- * </ul>
- * <p>
- * The server will validate map key types in an upcoming release.
- * <p>
- * All maps maintain an index and a rank.  The index is the item offset from the start of the map,
- * for both unordered and ordered maps.  The rank is the sorted index of the value component.
- * Map supports negative indexing for index and rank.
+ * Map bin operations for the client operate command. Default unique-key map is unordered. Valid
+ * map key types: String, Integer, byte[] (server will validate in an upcoming release). Maps have
+ * index (item offset) and rank (sorted index of value component); both support negative indexing.
+ * Use optional {@link CTX} for nested CDT paths.
  * <p>
- * Index examples:
+ * Index (item offset from start; negative = from end):
  * <ul>
- * <li>Index 0: First item in map.</li>
- * <li>Index 4: Fifth item in map.</li>
- * <li>Index -1: Last item in map.</li>
- * <li>Index -3: Third to last item in map.</li>
- * <li>Index 1 Count 2: Second and third items in map.</li>
- * <li>Index -3 Count 3: Last three items in map.</li>
- * <li>Index -5 Count 4: Range between fifth to last item to second to last item inclusive.</li>
+ * <li>Index 0: first item; 4: fifth item; -1: last item; -3: third to last.</li>
+ * <li>Index 1 Count 2: second and third items; Index -3 Count 3: last three items.</li>
+ * <li>Index -5 Count 4: range from fifth-to-last to second-to-last inclusive.</li>
  * </ul>
- * <p>
- * Rank examples:
+ * Rank (sorted index of value; negative = from highest):
  * <ul>
- * <li>Rank 0: Item with lowest value rank in map.</li>
- * <li>Rank 4: Fifth lowest ranked item in map.</li>
- * <li>Rank -1: Item with highest ranked value in map.</li>
- * <li>Rank -3: Item with third highest ranked value in map.</li>
- * <li>Rank 1 Count 2: Second and third lowest ranked items in map.</li>
- * <li>Rank -3 Count 3: Top three ranked items in map.</li>
- * </ul>
- * <p>
- * Nested CDT operations are supported by optional CTX context arguments.  Examples:
- * <ul>
- * <li>bin = {key1={key11=9,key12=4}, key2={key21=3,key22=5}}</li>
- * <li>Set map value to 11 for map key "key21" inside of map key "key2".</li>
- * <li>MapOperation.put(MapPolicy.Default, "bin", Value.get("key21"), Value.get(11), CTX.mapKey(Value.get("key2")))</li>
- * <li>bin result = {key1={key11=9,key12=4},key2={key21=11,key22=5}}</li>
- * <li></li>
- * <li>bin = {key1={key11={key111=1},key12={key121=5}}, key2={key21={"key211",7}}}</li>
- * <li>Set map value to 11 in map key "key121" for highest ranked map ("key12") inside of map key "key1".</li>
- * <li>MapOperation.put(MapPolicy.Default, "bin", Value.get("key121"), Value.get(11), CTX.mapKey(Value.get("key1")), CTX.mapRank(-1))</li>
- * <li>bin result = {key1={key11={key111=1},key12={key121=11}}, key2={key21={"key211",7}}}</li>
+ * <li>Rank 0: lowest ranked value; 4: fifth lowest; -1: highest ranked; -3: third highest.</li>
+ * <li>Rank 1 Count 2: second and third lowest; Rank -3 Count 3: top three ranked.</li>
  * </ul>
+ * <p>Put, getByKey, size, putItems; get by index/rank; nested put with CTX.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mapkey");
+ * client.delete(null, key);
+ *
+ * client.operate(null, key,
+ *     MapOperation.put(MapPolicy.Default, "bin", Value.get("name"), Value.get("Alice")),
+ *     MapOperation.put(MapPolicy.Default, "bin", Value.get("score"), Value.get(100)));
+ * Record rec = client.operate(null, key,
+ *     MapOperation.getByKey("bin", Value.get("name"), MapReturnType.VALUE),
+ *     MapOperation.size("bin"));
+ * String name = (String) rec.getList("bin").get(0);
+ * long size = (Long) rec.getList("bin").get(1);
+ *
+ * Map items = new HashMap<>();
+ * items.put(Value.get("a"), Value.get(1));
+ * items.put(Value.get("b"), Value.get(2));
+ * client.operate(null, key, MapOperation.putItems(MapPolicy.Default, "bin", items));
+ *
+ * // Index/rank: get by index 0 or -1, by rank 0 or -1
+ * client.operate(null, key, MapOperation.getByIndex("bin", 0, MapReturnType.VALUE));
+ * client.operate(null, key, MapOperation.getByIndex("bin", -1, MapReturnType.VALUE));
+ * client.operate(null, key, MapOperation.getByRank("bin", 0, MapReturnType.VALUE));
+ * client.operate(null, key, MapOperation.getByRank("bin", -1, MapReturnType.VALUE));
+ *
+ * // Nested: put value 11 at key "key21" inside map key "key2" (bin = {key1={...}, key2={key21=3,key22=5}})
+ * client.operate(null, key, MapOperation.put(MapPolicy.Default, "bin", Value.get("key21"), Value.get(11), CTX.mapKey(Value.get("key2"))));
+ * // Nested with rank: put 11 at "key121" in highest-ranked map in "key1" (CTX.mapKey(key1), CTX.mapRank(-1))
+ * client.operate(null, key, MapOperation.put(MapPolicy.Default, "bin", Value.get("key121"), Value.get(11), CTX.mapKey(Value.get("key1")), CTX.mapRank(-1)));
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see CTX
+ * @see MapPolicy
+ * @see MapReturnType
  */
 public class MapOperation {
 	private static final int SET_TYPE = 64;
diff --git a/client/src/com/aerospike/client/cdt/MapOrder.java b/client/src/com/aerospike/client/cdt/MapOrder.java
index 2fbd25417..b6371feb7 100644
--- a/client/src/com/aerospike/client/cdt/MapOrder.java
+++ b/client/src/com/aerospike/client/cdt/MapOrder.java
@@ -17,7 +17,12 @@
 package com.aerospike.client.cdt;
 
 /**
- * Map storage order.
+ * Map storage order; used in {@link MapPolicy} and {@link MapOperation}.
+ * <p>
+ * Use {@link #KEY_ORDERED} or {@link #KEY_VALUE_ORDERED} for rank/getByRank; default is {@link #UNORDERED}.
+ *
+ * @see MapPolicy
+ * @see MapOperation
  */
 public enum MapOrder {
 	/**
diff --git a/client/src/com/aerospike/client/cdt/MapPolicy.java b/client/src/com/aerospike/client/cdt/MapPolicy.java
index 5ae4dcce4..b96410289 100644
--- a/client/src/com/aerospike/client/cdt/MapPolicy.java
+++ b/client/src/com/aerospike/client/cdt/MapPolicy.java
@@ -17,12 +17,25 @@
 package com.aerospike.client.cdt;
 
 /**
- * Map policy directives when creating a map and writing map items.
+ * Map policy: order and write flags when creating a map or writing map items.
+ * <p>
+ * Use with {@link MapOperation#put}, {@link MapOperation#putItems}, {@link MapOperation#replace}, etc. when the map may not exist or when you need key-ordered or update semantics.
+ * <p>Use MapPolicy with put and putItems.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * MapPolicy policy = MapPolicy.Default;
+ * client.operate(null, key, MapOperation.put(policy, "bin", Value.get("k"), Value.get(42)));
+ *
+ * MapPolicy keyOrdered = new MapPolicy(MapOrder.KEY_ORDERED, MapWriteFlags.DEFAULT);
+ * client.operate(null, key, MapOperation.putItems(keyOrdered, "bin", map));
+ * }</pre>
+ *
+ * @see MapOperation
+ * @see MapOrder
+ * @see MapWriteFlags
  */
 public final class MapPolicy {
-	/**
-	 * Default unordered unique key map with normal put semantics.
-	 */
+	/** Default unordered unique-key map with normal put semantics. */
 	public static final MapPolicy Default = new MapPolicy();
 
 	public final int attributes;
diff --git a/client/src/com/aerospike/client/cdt/MapReturnType.java b/client/src/com/aerospike/client/cdt/MapReturnType.java
index 755a5828d..462f8b42d 100644
--- a/client/src/com/aerospike/client/cdt/MapReturnType.java
+++ b/client/src/com/aerospike/client/cdt/MapReturnType.java
@@ -17,7 +17,17 @@
 package com.aerospike.client.cdt;
 
 /**
- * Map return type. Type of data to return when selecting or removing items from the map.
+ * What to return from map read/remove operations (key, value, index, rank, count, etc.).
+ * <p>
+ * Pass to {@link MapOperation#getByKey}, {@link MapOperation#getByIndex}, {@link MapOperation#getByRank}, {@link MapOperation#removeByKey}, and similar.
+ * <p>Use MapReturnType in getByKey and getByRank.</p>
+ * <pre>{@code
+ * Record rec = client.operate(null, key,
+ *     MapOperation.getByKey("bin", Value.get("name"), MapReturnType.VALUE),
+ *     MapOperation.getByRank("bin", -1, MapReturnType.KEY_VALUE));
+ * }</pre>
+ *
+ * @see MapOperation
  */
 public final class MapReturnType {
 	/**
diff --git a/client/src/com/aerospike/client/cdt/MapWriteFlags.java b/client/src/com/aerospike/client/cdt/MapWriteFlags.java
index 3aea468a8..e656729dc 100644
--- a/client/src/com/aerospike/client/cdt/MapWriteFlags.java
+++ b/client/src/com/aerospike/client/cdt/MapWriteFlags.java
@@ -17,11 +17,15 @@
 package com.aerospike.client.cdt;
 
 /**
- * Map write bit flags. Use BITWISE OR to combine flags. Example:
- * 
- * <pre>{@code 
+ * Map write bit flags; combine with BITWISE OR and pass to {@link MapPolicy}.
+ * <p>
+ * <p>Combine map write flags and pass to MapPolicy.</p>
+ * <pre>{@code
  * int flags = MapWriteFlags.UPDATE_ONLY | MapWriteFlags.NO_FAIL | MapWriteFlags.PARTIAL;
+ * MapPolicy policy = new MapPolicy(MapOrder.KEY_ORDERED, flags);
  * }</pre>
+ *
+ * @see MapPolicy
  */
 public final class MapWriteFlags {
 	/**
diff --git a/client/src/com/aerospike/client/configuration/ConfigurationProvider.java b/client/src/com/aerospike/client/configuration/ConfigurationProvider.java
index 8e14cf013..9288af4b2 100644
--- a/client/src/com/aerospike/client/configuration/ConfigurationProvider.java
+++ b/client/src/com/aerospike/client/configuration/ConfigurationProvider.java
@@ -19,9 +19,42 @@
 
 import com.aerospike.client.configuration.serializers.Configuration;
 
+/**
+ * Supplies static and dynamic client configuration (e.g. from YAML). Pass to {@link com.aerospike.client.policy.ClientPolicy#ClientPolicy(com.aerospike.client.policy.ClientPolicy, com.aerospike.client.configuration.ConfigurationProvider)} so policies can load and apply config.
+ * <p>
+ * The client and policy constructors that take a ConfigurationProvider use it to populate policy fields from the fetched {@link Configuration}. Implement this interface to provide config from a custom source.
+ * <pre>{@code
+ * ConfigurationProvider provider = YamlConfigProvider.getConfigProvider("file:///path/to/config.yaml");
+ * ClientPolicy clientPolicy = new ClientPolicy(new ClientPolicy(), provider);
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ *
+ * ConfigurationProvider fromClient = client.getConfigProvider();
+ * if (fromClient != null && fromClient.loadConfiguration()) {
+ *   Configuration config = fromClient.fetchConfiguration();
+ * }
+ * }</pre>
+ *
+ * @see Configuration
+ * @see YamlConfigProvider
+ * @see com.aerospike.client.policy.ClientPolicy#ClientPolicy(ClientPolicy, ConfigurationProvider)
+ * @see com.aerospike.client.IAerospikeClient#getConfigProvider()
+ */
 public interface ConfigurationProvider {
+    /**
+     * Loads or reloads configuration from the provider source.
+     * @return true if configuration was loaded successfully
+     */
     boolean loadConfiguration();
 
+    /**
+     * Returns the current static and dynamic configuration snapshot.
+     * @return configuration (must not be null)
+     */
     Configuration fetchConfiguration();
+
+    /**
+     * Returns the dynamic part of configuration (for runtime updates).
+     * @return dynamic configuration (must not be null)
+     */
     Configuration fetchDynamicConfiguration();
 }
diff --git a/client/src/com/aerospike/client/exp/BitExp.java b/client/src/com/aerospike/client/exp/BitExp.java
index a92ad5ab1..c831c37d7 100644
--- a/client/src/com/aerospike/client/exp/BitExp.java
+++ b/client/src/com/aerospike/client/exp/BitExp.java
@@ -23,7 +23,7 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Bit expression generator. See {@link com.aerospike.client.exp.Exp}.
+ * Bit (blob) expression generator for filters and operate; see {@link Exp}.
  * <p>
  * The bin expression argument in these methods can be a reference to a bin or the
  * result of another expression. Expressions that modify bin values are only used
@@ -33,6 +33,21 @@
  * Offset orientation is left-to-right.  Negative offsets are supported.
  * If the offset is negative, the offset starts backwards from end of the bitmap.
  * If an offset is out of bounds, a parameter error will be returned.
+ * <p>Filter or read by bit count and resize expression.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Expression exp = Exp.build(Exp.eq(BitExp.count(Exp.blobBin("bits"), 0, -1), Exp.val(5)));
+ * Policy policy = new Policy();
+ * policy.filterExp = exp;
+ * Record rec = client.get(policy, key);
+ *
+ * Expression resizeExp = Exp.build(BitExp.resize(Exp.blobBin("a"), 4, BitResizeFlags.DEFAULT));
+ * Record r = client.operate(null, key, ExpOperation.read("a", resizeExp, ExpReadFlags.DEFAULT));
+ * }</pre>
+ *
+ * @see Exp
+ * @see com.aerospike.client.operation.BitResizeFlags
+ * @see com.aerospike.client.operation.BitPolicy
  */
 public final class BitExp {
 	private static final int MODULE = 1;
@@ -66,6 +81,7 @@ public final class BitExp {
 	 * <li>resizeFlags = 0</li>
 	 * <li>returns [0b00000001, 0b01000010, 0b00000000, 0b00000000]</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Resize bin "a" and compare bit count
 	 * Exp.eq(
@@ -87,6 +103,7 @@ public static Exp resize(BitPolicy policy, Exp byteSize, int resizeFlags, Exp bi
 	 * <li>value = [0b11111111, 0b11000111]</li>
 	 * <li>bin result = [0b00000001, 0b11111111, 0b11000111, 0b01000010, 0b00000011, 0b00000100, 0b00000101]</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Insert bytes into bin "a" and compare bit count
 	 * Exp.eq(
@@ -108,6 +125,7 @@ public static Exp insert(BitPolicy policy, Exp byteOffset, Exp value, Exp bin) {
 	 * <li>byteSize = 3</li>
 	 * <li>bin result = [0b00000001, 0b01000010]</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Remove bytes from bin "a" and compare bit count
 	 * Exp.eq(
@@ -130,6 +148,7 @@ public static Exp remove(BitPolicy policy, Exp byteOffset, Exp byteSize, Exp bin
 	 * <li>value = [0b11100000]</li>
 	 * <li>bin result = [0b00000001, 0b01000111, 0b00000011, 0b00000100, 0b00000101]</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Set bytes in bin "a" and compare bit count
 	 * Exp.eq(
@@ -311,6 +330,7 @@ public static Exp setInt(BitPolicy policy, Exp bitOffset, Exp bitSize, Exp value
 	 * <li>bitSize = 5</li>
 	 * <li>returns [0b10000000]</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Bin "a" bits = [0b10000000]
 	 * Exp.eq(
@@ -332,6 +352,7 @@ public static Exp get(Exp bitOffset, Exp bitSize, Exp bin) {
 	 * <li>bitSize = 4</li>
 	 * <li>returns 2</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Bin "a" bit count <= 2
 	 * Exp.le(BitExp.count(Exp.val(0), Exp.val(5), Exp.blobBin("a")), Exp.val(2))
@@ -352,6 +373,7 @@ public static Exp count(Exp bitOffset, Exp bitSize, Exp bin) {
 	 * <li>value = true</li>
 	 * <li>returns 5</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // lscan(a) == 5
 	 * Exp.eq(BitExp.lscan(Exp.val(24), Exp.val(8), Exp.val(true), Exp.blobBin("a")), Exp.val(5))
@@ -378,6 +400,7 @@ public static Exp lscan(Exp bitOffset, Exp bitSize, Exp value, Exp bin) {
 	 * <li>value = true</li>
 	 * <li>returns 7</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // rscan(a) == 7
 	 * Exp.eq(BitExp.rscan(Exp.val(32), Exp.val(8), Exp.val(true), Exp.blobBin("a")), Exp.val(7))
@@ -403,6 +426,7 @@ public static Exp rscan(Exp bitOffset, Exp bitSize, Exp value, Exp bin) {
 	 * <li>signed = false</li>
 	 * <li>returns 16899</li>
 	 * </ul>
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // getInt(a) == 16899
 	 * Exp.eq(BitExp.getInt(Exp.val(8), Exp.val(16), false, Exp.blobBin("a")), Exp.val(16899))
diff --git a/client/src/com/aerospike/client/exp/CdtExp.java b/client/src/com/aerospike/client/exp/CdtExp.java
index b933391e6..23fe9d5e9 100644
--- a/client/src/com/aerospike/client/exp/CdtExp.java
+++ b/client/src/com/aerospike/client/exp/CdtExp.java
@@ -13,12 +13,30 @@
  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  * License for the specific language governing permissions and limitations under
  * the License.
-*/ 
+*/
 package com.aerospike.client.exp;
 
 import com.aerospike.client.cdt.CTX;
 import com.aerospike.client.util.Packer;
 
+/**
+ * CDT select/modify expressions for use in filters and expressions (nested path select/apply).
+ * <p>
+ * Use with {@link Exp#build(Exp)} in {@link com.aerospike.client.policy.Policy#filterExp} or inside other expressions. Complements {@link com.aerospike.client.cdt.CdtOperation} (operate-only) with expression form for filtering.
+ * <p>Filter by nested path with CdtExp.selectByPath.</p>
+ * <pre>{@code
+ * CTX ctx1 = CTX.mapKey(Value.get("book"));
+ * CTX ctx2 = CTX.allChildrenWithFilter(Exp.le(MapExp.getByKey(MapReturnType.VALUE, Exp.Type.FLOAT, Exp.val("price"), Exp.mapLoopVar(LoopVarPart.VALUE)), Exp.val(10.0)));
+ * Exp selectExp = CdtExp.selectByPath(Exp.Type.LIST, Exp.SELECT_VALUE, Exp.mapBin("bin"), ctx1, ctx2);
+ * Policy policy = new Policy();
+ * policy.filterExp = Exp.build(selectExp);
+ * }</pre>
+ *
+ * @see Exp
+ * @see com.aerospike.client.cdt.CdtOperation
+ * @see CTX
+ * @see LoopVarPart
+ */
 public class CdtExp {
     /**
      * The module identifier for CDT expressions.
diff --git a/client/src/com/aerospike/client/exp/Exp.java b/client/src/com/aerospike/client/exp/Exp.java
index 5b3439b03..ceacea999 100644
--- a/client/src/com/aerospike/client/exp/Exp.java
+++ b/client/src/com/aerospike/client/exp/Exp.java
@@ -23,7 +23,32 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Expression generator.
+ * Expression generator for filters, queries, and operate read/write.
+ * <p>
+ * Build expressions with {@link #build(Exp)} then use on {@link com.aerospike.client.policy.WritePolicy#filterExp}, {@link com.aerospike.client.policy.Policy#filterExp}, {@link com.aerospike.client.query.Statement#setFilter}, or {@link com.aerospike.client.exp.ExpOperation#read} / {@link ExpOperation#write}. Use {@link ListExp}, {@link MapExp}, and {@link CdtExp} for CDT bin expressions.
+ * <p>Use filter expressions on put, get, and ExpOperation.read.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * WritePolicy policy = new WritePolicy();
+ * policy.filterExp = Exp.build(Exp.eq(Exp.intBin("A"), Exp.val(1)));
+ * client.put(policy, key, new Bin("A", 3));
+ *
+ * Policy readPolicy = new Policy();
+ * readPolicy.filterExp = Exp.build(Exp.gt(Exp.intBin("score"), Exp.val(100)));
+ * Record rec = client.get(readPolicy, key);
+ *
+ * Expression exp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(4)));
+ * Record rec2 = client.operate(null, key, ExpOperation.read("EV", exp, ExpReadFlags.DEFAULT));
+ * }</pre>
+ *
+ * @see Expression
+ * @see ExpOperation
+ * @see ListExp
+ * @see MapExp
+ * @see CdtExp
+ * @see com.aerospike.client.policy.WritePolicy#filterExp
  */
 public abstract class Exp {
 	/**
@@ -1228,7 +1253,7 @@ public static Exp hllLoopVar(LoopVarPart part) {
 	/**
 	 * Create expression that references a built-in variable.
 	 * Requires server version 8.1.1
-	 * 
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * Exp.intLoopVar(LoopVarPart.MAP_KEY)
 	 * }</pre>
@@ -1240,7 +1265,7 @@ public static Exp intLoopVar(LoopVarPart part) {
 	/**
 	 * Create expression that references a built-in variable.
 	 * Requires server version 8.1.1
-	 * 
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * Exp.floatLoopVar(LoopVarPart.MAP_KEY)
 	 * }</pre>
@@ -1252,7 +1277,7 @@ public static Exp floatLoopVar(LoopVarPart part) {
 	/**
 	 * Create expression that references a built-in variable.
 	 * Requires server version 8.1.1
-	 * 
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * Exp.listLoopVar(LoopVarPart.MAP_KEY)
 	 * }</pre>
@@ -1264,7 +1289,7 @@ public static Exp listLoopVar(LoopVarPart part)	{
 	/**
 	 * Create expression that references a built-in variable.
 	 * Requires server version 8.1.1
-	 * 
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * Exp.mapLoopVar(LoopVarPart.MAP_KEY)
 	 * }</pre>
@@ -1276,7 +1301,7 @@ public static Exp mapLoopVar(LoopVarPart part)	{
 	/**
 	 * Create expression that references a built-in variable.
 	 * Requires server version 8.1.1
-	 * 
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * Exp.blobLoopVar(LoopVarPart.MAP_KEY)
 	 * }</pre>
@@ -1288,7 +1313,7 @@ public static Exp blobLoopVar(LoopVarPart part)	{
 	/**
 	 * Create expression that references a built-in variable.
 	 * Requires server version 8.1.1
-	 * 
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * Exp.nilLoopVar(LoopVarPart.MAP_KEY)
 	 * }</pre>
@@ -1300,7 +1325,7 @@ public static Exp nilLoopVar(LoopVarPart part)	{
 	/**
 	 * Create expression that references a built-in variable.
 	 * Requires server version 8.1.1
-	 * 
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * Exp.geoJsonLoopVar(LoopVarPart.MAP_KEY)
 	 * }</pre>
diff --git a/client/src/com/aerospike/client/exp/ExpOperation.java b/client/src/com/aerospike/client/exp/ExpOperation.java
index 5633e2c49..47c70a3f1 100644
--- a/client/src/com/aerospike/client/exp/ExpOperation.java
+++ b/client/src/com/aerospike/client/exp/ExpOperation.java
@@ -21,7 +21,31 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Expression operations.
+ * Read and write operations that evaluate expressions on the server (server 5.6+).
+ * <p>
+ * Use with {@link com.aerospike.client.AerospikeClient#operate}. Read stores the expression result in a bin-name variable; write stores the result in the given bin.
+ * <p>Write and read expression results with operate.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * client.put(null, key, new Bin("A", 1), new Bin("D", 2));
+ *
+ * Expression wexp = Exp.build(Exp.intBin("D"));
+ * Expression rexp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(4)));
+ * Record rec = client.operate(null, key,
+ *     ExpOperation.write("D", wexp, ExpWriteFlags.DEFAULT),
+ *     ExpOperation.read("EV", rexp, ExpReadFlags.DEFAULT));
+ * long ev = rec.getLong("EV");
+ *
+ * Expression writeExp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(10)));
+ * client.operate(null, key, ExpOperation.write("C", writeExp, ExpWriteFlags.DEFAULT));
+ * }</pre>
+ *
+ * @see Exp
+ * @see Expression
+ * @see ExpReadFlags
+ * @see ExpWriteFlags
+ * @see com.aerospike.client.AerospikeClient#operate
  */
 public final class ExpOperation {
 	/**
diff --git a/client/src/com/aerospike/client/exp/ExpReadFlags.java b/client/src/com/aerospike/client/exp/ExpReadFlags.java
index d59449550..078341c85 100644
--- a/client/src/com/aerospike/client/exp/ExpReadFlags.java
+++ b/client/src/com/aerospike/client/exp/ExpReadFlags.java
@@ -17,16 +17,21 @@
 package com.aerospike.client.exp;
 
 /**
- * Expression read flags.
+ * Flags for {@link ExpOperation#read}; control behavior when expression evaluation fails (e.g. missing bin).
+ * <p>
+ * Use with {@link ExpOperation#read}. {@link #EVAL_NO_FAIL} returns the record without the expression result instead of failing.
+ * <p>Use ExpReadFlags with ExpOperation.read.</p>
+ * <pre>{@code
+ * Record rec = client.operate(null, key, ExpOperation.read("EV", exp, ExpReadFlags.DEFAULT));
+ * Record rec2 = client.operate(null, key, ExpOperation.read("EV", exp, ExpReadFlags.EVAL_NO_FAIL));
+ * }</pre>
+ *
+ * @see ExpOperation#read
  */
 public final class ExpReadFlags {
-	/**
-	 * Default.
-	 */
+	/** Default: fail if expression cannot be evaluated (e.g. bin missing). */
 	public static final int DEFAULT = 0;
 
-	/**
-	 * Ignore failures caused by the expression resolving to unknown or a non-bin type.
-	 */
+	/** Ignore failures when expression resolves to unknown or non-bin type; record still returned. */
 	public static final int EVAL_NO_FAIL = 16;
 }
diff --git a/client/src/com/aerospike/client/exp/ExpWriteFlags.java b/client/src/com/aerospike/client/exp/ExpWriteFlags.java
index 2864a9738..571ce8bb7 100644
--- a/client/src/com/aerospike/client/exp/ExpWriteFlags.java
+++ b/client/src/com/aerospike/client/exp/ExpWriteFlags.java
@@ -17,11 +17,15 @@
 package com.aerospike.client.exp;
 
 /**
- * Expression write bit flags. Use BITWISE OR to combine flags. Example:
- * 
- * <pre>{@code 
+ * Flags for {@link ExpOperation#write}; combine with BITWISE OR. Control create/update and failure behavior.
+ * <p>
+ * <p>Combine ExpWriteFlags and pass to ExpOperation.write.</p>
+ * <pre>{@code
  * int flags = ExpWriteFlags.CREATE_ONLY | ExpWriteFlags.POLICY_NO_FAIL;
+ * client.operate(null, key, ExpOperation.write("bin", exp, flags));
  * }</pre>
+ *
+ * @see ExpOperation#write
  */
 public final class ExpWriteFlags {
 	/**
diff --git a/client/src/com/aerospike/client/exp/Expression.java b/client/src/com/aerospike/client/exp/Expression.java
index aa3111a92..f2fe4370f 100644
--- a/client/src/com/aerospike/client/exp/Expression.java
+++ b/client/src/com/aerospike/client/exp/Expression.java
@@ -24,7 +24,23 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Packed expression byte instructions.
+ * Packed expression built from {@link Exp}; use in filter policies, query filters, and {@link ExpOperation}.
+ * <p>
+ * Create with {@link Exp#build(Exp)}. Use {@link #getBytes()} or {@link #fromBytes(byte[])} / {@link #fromBase64(String)} for serialization.
+ * <p>Build expression for filter and ExpOperation.read.</p>
+ * <pre>{@code
+ * Expression exp = Exp.build(Exp.eq(Exp.intBin("A"), Exp.val(1)));
+ * WritePolicy policy = new WritePolicy();
+ * policy.filterExp = exp;
+ * client.put(policy, key, new Bin("A", 2));
+ *
+ * Expression readExp = Exp.build(Exp.add(Exp.intBin("A"), Exp.val(10)));
+ * Record rec = client.operate(null, key, ExpOperation.read("result", readExp, ExpReadFlags.DEFAULT));
+ * long result = rec.getLong("result");
+ * }</pre>
+ *
+ * @see Exp
+ * @see ExpOperation
  */
 public final class Expression implements Serializable {
 	private static final long serialVersionUID = 1L;
diff --git a/client/src/com/aerospike/client/exp/HLLExp.java b/client/src/com/aerospike/client/exp/HLLExp.java
index 999256eb4..9faf0b7e6 100644
--- a/client/src/com/aerospike/client/exp/HLLExp.java
+++ b/client/src/com/aerospike/client/exp/HLLExp.java
@@ -20,12 +20,27 @@
 import com.aerospike.client.util.Pack;
 
 /**
- * HyperLogLog (HLL) expression generator. See {@link com.aerospike.client.exp.Exp}.
+ * HyperLogLog (HLL) expression generator for filters and operate; see {@link Exp}.
  * <p>
  * The bin expression argument in these methods can be a reference to a bin or the
  * result of another expression. Expressions that modify bin values are only used
  * for temporary expression evaluation and are not permanently applied to the bin.
  * HLL modify expressions return the HLL bin's value.
+ * <p>Below example illustrates filter by HLL count and read count with ExpOperation.</p>
+ * <pre>{@code
+ * Expression exp = Exp.build(Exp.ge(HLLExp.count(Exp.hllBin("h")), Exp.val(10)));
+ * Policy policy = new Policy();
+ * policy.filterExp = exp;
+ * Record rec = client.get(policy, key);
+ *
+ * Expression countExp = Exp.build(HLLExp.count(Exp.hllBin("h")));
+ * Record r = client.operate(null, key, ExpOperation.read("cnt", countExp, ExpReadFlags.DEFAULT));
+ * long cnt = r.getLong("cnt");
+ * }</pre>
+ *
+ * @see Exp
+ * @see com.aerospike.client.operation.HLLOperation
+ * @see com.aerospike.client.operation.HLLPolicy
  */
 public final class HLLExp {
 	private static final int MODULE = 2;
@@ -67,7 +82,7 @@ public static Exp init(HLLPolicy policy, Exp indexBitCount, Exp minHashBitCount,
 	/**
 	 * Create expression that adds list values to a HLL set and returns HLL set.
 	 * The function assumes HLL bin already exists.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Add values to HLL bin "a" and check count > 7
 	 * Exp.gt(
@@ -87,7 +102,7 @@ public static Exp add(HLLPolicy policy, Exp list, Exp bin) {
 	/**
 	 * Create expression that adds values to a HLL set and returns HLL set.
 	 * If HLL bin does not exist, use indexBitCount to create HLL bin.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Add values to HLL bin "a" and check count > 7
 	 * Exp.gt(
@@ -108,7 +123,7 @@ public static Exp add(HLLPolicy policy, Exp list, Exp indexBitCount, Exp bin) {
 	/**
 	 * Create expression that adds values to a HLL set and returns HLL set. If HLL bin does not
 	 * exist, use indexBitCount and minHashBitCount to create HLL set.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Add values to HLL bin "a" and check count > 7
 	 * Exp.gt(
@@ -131,7 +146,7 @@ public static Exp add(HLLPolicy policy, Exp list, Exp indexBitCount, Exp minHash
 
 	/**
 	 * Create expression that returns estimated number of elements in the HLL bin.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // HLL bin "a" count > 7
 	 * Exp.gt(HLLExp.getCount(Exp.hllBin("a")), Exp.val(7))
@@ -145,7 +160,7 @@ public static Exp getCount(Exp bin) {
 	/**
 	 * Create expression that returns a HLL object that is the union of all specified HLL objects
 	 * in the list with the HLL bin.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Union of HLL bins "a" and "b"
 	 * HLLExp.getUnion(Exp.hllBin("a"), Exp.hllBin("b"))
@@ -162,7 +177,7 @@ public static Exp getUnion(Exp list, Exp bin) {
 	/**
 	 * Create expression that returns estimated number of elements that would be contained by
 	 * the union of these HLL objects.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Union count of HLL bins "a" and "b"
 	 * HLLExp.getUnionCount(Exp.hllBin("a"), Exp.hllBin("b"))
@@ -179,7 +194,7 @@ public static Exp getUnionCount(Exp list, Exp bin) {
 	/**
 	 * Create expression that returns estimated number of elements that would be contained by
 	 * the intersection of these HLL objects.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Intersect count of HLL bins "a" and "b"
 	 * HLLExp.getIntersectCount(Exp.hllBin("a"), Exp.hllBin("b"))
@@ -196,7 +211,7 @@ public static Exp getIntersectCount(Exp list, Exp bin) {
 	/**
 	 * Create expression that returns estimated similarity of these HLL objects as a
 	 * 64 bit float.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Similarity of HLL bins "a" and "b" >= 0.75
 	 * Exp.ge(HLLExp.getSimilarity(Exp.hllBin("a"), Exp.hllBin("b")), Exp.val(0.75))
@@ -210,7 +225,7 @@ public static Exp getSimilarity(Exp list, Exp bin) {
 	/**
 	 * Create expression that returns indexBitCount and minHashBitCount used to create HLL bin
 	 * in a list of longs. list[0] is indexBitCount and list[1] is minHashBitCount.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Bin "a" indexBitCount < 10
 	 * Exp.lt(
@@ -226,7 +241,7 @@ public static Exp describe(Exp bin) {
 
 	/**
 	 * Create expression that returns one if HLL bin may contain all items in the list.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Bin "a" may contain value "x"
 	 * ArrayList<Value> list = new ArrayList<Value>();
diff --git a/client/src/com/aerospike/client/exp/ListExp.java b/client/src/com/aerospike/client/exp/ListExp.java
index bbea91fd0..d0ac80d7e 100644
--- a/client/src/com/aerospike/client/exp/ListExp.java
+++ b/client/src/com/aerospike/client/exp/ListExp.java
@@ -25,37 +25,49 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * List expression generator. See {@link com.aerospike.client.exp.Exp}.
+ * List expression generator for filters and operate; see {@link Exp}.
  * <p>
- * The bin expression argument in these methods can be a reference to a bin or the
- * result of another expression. Expressions that modify bin values are only used
- * for temporary expression evaluation and are not permanently applied to the bin.
+ * The bin argument can be a bin reference or an expression that returns a list. List modify
+ * expressions return the bin's value (a list, or a map when the list is nested in a map). Negative
+ * indexing is supported; index out of bounds returns a parameter error; a range partially out of
+ * bounds returns the valid part. Use optional {@link com.aerospike.client.cdt.CTX} for nested
+ * lists/maps.
  * <p>
- * List modify expressions return the bin's value. This value will be a list except
- * when the list is nested within a map. In that case, a map is returned for the
- * list modify expression.
- * <p>
- * List expressions support negative indexing. If the index is negative, the
- * resolved index starts backwards from end of list. If an index is out of bounds,
- * a parameter error will be returned. If a range is partially out of bounds, the
- * valid part of the range will be returned. Index/Range examples:
- * <ul>
- * <li>Index 0: First item in list.</li>
- * <li>Index 4: Fifth item in list.</li>
- * <li>Index -1: Last item in list.</li>
- * <li>Index -3: Third to last item in list.</li>
- * <li>Index 1 Count 2: Second and third items in list.</li>
- * <li>Index -3 Count 3: Last three items in list.</li>
- * <li>Index -5 Count 4: Range between fifth to last item to second to last item inclusive.</li>
- * </ul>
- * <p>
- * Nested expressions are supported by optional CTX context arguments.  Example:
+ * Index (item offset; negative = from end):
  * <ul>
- * <li>bin = [[7,9,5],[1,2,3],[6,5,4,1]]</li>
- * <li>Get size of last list.</li>
- * <li>ListExp.size(Exp.listBin("bin"), CTX.listIndex(-1))</li>
- * <li>result = 4</li>
+ * <li>Index 0: first item; 4: fifth item; -1: last item; -3: third to last.</li>
+ * <li>Index 1 Count 2: second and third items; Index -3 Count 3: last three items.</li>
+ * <li>Index -5 Count 4: range from fifth-to-last to second-to-last inclusive.</li>
  * </ul>
+ * <p>Filter by list size, read by index/range, and nested CTX (e.g. size of last list).</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * // Filter by list size (e.g. list at CTX listIndex 4 has size 6)
+ * Policy policy = new Policy();
+ * policy.filterExp = Exp.build(Exp.eq(ListExp.size(Exp.listBin("A"), CTX.listIndex(4)), Exp.val(6)));
+ * Record rec = client.get(policy, key);
+ *
+ * // Index: first (0), last (-1), range second+third (1, count 2), last three (-3, count 3), -5 count 4
+ * Exp byIndex0 = ListExp.getByIndex(ListReturnType.VALUE, Exp.Type.INT, Exp.val(0), Exp.listBin("bin"));
+ * Exp byIndexLast = ListExp.getByIndex(ListReturnType.VALUE, Exp.Type.INT, Exp.val(-1), Exp.listBin("bin"));
+ * Exp byIndexRange = ListExp.getByIndexRange(ListReturnType.VALUE, Exp.val(1), Exp.val(2), Exp.listBin("bin"));
+ * Exp lastThree = ListExp.getByIndexRange(ListReturnType.VALUE, Exp.val(-3), Exp.val(3), Exp.listBin("bin"));
+ * Exp rangeFromFifthToLast = ListExp.getByIndexRange(ListReturnType.VALUE, Exp.val(-5), Exp.val(4), Exp.listBin("bin"));
+ *
+ * // List modify (returns bin value)
+ * Expression exp = Exp.build(ListExp.getByIndex(ListReturnType.VALUE, Exp.Type.INT, Exp.val(0), Exp.listBin("bin")));
+ * Record r = client.operate(null, key, ExpOperation.read("first", exp, ExpReadFlags.DEFAULT));
+ *
+ * // Nested: size of last list (bin = [[7,9,5],[1,2,3],[6,5,4,1]] -> result 4)
+ * Exp sizeOfLastList = ListExp.size(Exp.listBin("bin"), CTX.listIndex(-1));
+ * }</pre>
+ *
+ * @see Exp
+ * @see MapExp
+ * @see com.aerospike.client.cdt.CTX
+ * @see com.aerospike.client.cdt.ListReturnType
  */
 public final class ListExp {
 	private static final int MODULE = 0;
@@ -286,7 +298,7 @@ public static Exp removeByRankRange(int returnType, Exp rank, Exp count, Exp bin
 
 	/**
 	 * Create expression that returns list size.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // List bin "a" size > 7
 	 * Exp.gt(ListExp.size(Exp.listBin("a")), Exp.val(7))
@@ -300,7 +312,7 @@ public static Exp size(Exp bin, CTX... ctx) {
 	/**
 	 * Create expression that selects list items identified by value and returns selected
 	 * data specified by returnType.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // List bin "a" contains at least one item == "abc"
 	 * ListExp.getByValue(ListReturnType.EXISTS, Exp.val("abc"), Exp.listBin("a"))
@@ -319,7 +331,7 @@ public static Exp getByValue(int returnType, Exp value, Exp bin, CTX... ctx) {
 	/**
 	 * Create expression that selects list items identified by value range and returns selected data
 	 * specified by returnType.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // List bin "a" items >= 10 && items < 20
 	 * ListExp.getByValueRange(ListReturnType.VALUE, Exp.val(10), Exp.val(20), Exp.listBin("a"))
@@ -388,7 +400,7 @@ public static Exp getByValueRelativeRankRange(int returnType, Exp value, Exp ran
 	/**
 	 * Create expression that selects list item identified by index and returns
 	 * selected data specified by returnType.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // a[3] == 5
 	 * Exp.eq(
@@ -428,7 +440,7 @@ public static Exp getByIndexRange(int returnType, Exp index, Exp count, Exp bin,
 	/**
 	 * Create expression that selects list item identified by rank and returns selected
 	 * data specified by returnType.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Player with lowest score.
 	 * ListExp.getByRank(ListReturnType.VALUE, Type.STRING, Exp.val(0), Exp.listBin("a"))
diff --git a/client/src/com/aerospike/client/exp/LoopVarPart.java b/client/src/com/aerospike/client/exp/LoopVarPart.java
index bf0baa921..98a98a162 100644
--- a/client/src/com/aerospike/client/exp/LoopVarPart.java
+++ b/client/src/com/aerospike/client/exp/LoopVarPart.java
@@ -17,8 +17,19 @@
 package com.aerospike.client.exp;
 
 /**
- * Loop variable parts for expression loop variables.
- * Used to specify which part of a loop variable to access during iteration.
+ * Which part of a loop variable to use in iteration expressions (e.g. in {@link com.aerospike.client.cdt.CTX#allChildrenWithFilter(Exp)} and CDT apply).
+ * <p>
+ * Use with {@link Exp#mapLoopVar}, {@link Exp#stringLoopVar}, {@link Exp#intLoopVar}, {@link Exp#floatLoopVar} when building filter/apply expressions over map or list elements.
+ * <p>Filter nested children by loop variable key or value.</p>
+ * <pre>{@code
+ * CTX ctx = CTX.allChildrenWithFilter(Exp.eq(Exp.stringLoopVar(LoopVarPart.MAP_KEY), Exp.val("title")));
+ * CTX ctx2 = CTX.allChildrenWithFilter(Exp.le(MapExp.getByKey(MapReturnType.VALUE, Exp.Type.FLOAT, Exp.val("price"), Exp.mapLoopVar(LoopVarPart.VALUE)), Exp.val(10.0)));
+ * }</pre>
+ *
+ * @see Exp#mapLoopVar
+ * @see Exp#stringLoopVar
+ * @see com.aerospike.client.cdt.CTX#allChildrenWithFilter(Exp)
+ * @see com.aerospike.client.cdt.CdtOperation#modifyByPath
  */
 public enum LoopVarPart {
 	/**
diff --git a/client/src/com/aerospike/client/exp/MapExp.java b/client/src/com/aerospike/client/exp/MapExp.java
index 3e400a057..9dfcd8382 100644
--- a/client/src/com/aerospike/client/exp/MapExp.java
+++ b/client/src/com/aerospike/client/exp/MapExp.java
@@ -23,58 +23,66 @@
 import com.aerospike.client.util.Pack;
 
 /**
- * Map expression generator. See {@link com.aerospike.client.exp.Exp}.
+ * Map expression generator for filters and operate; see {@link Exp}.
  * <p>
- * The bin expression argument in these methods can be a reference to a bin or the
- * result of another expression. Expressions that modify bin values are only used
- * for temporary expression evaluation and are not permanently applied to the bin.
+ * The bin argument can be a bin reference or an expression that returns a map. Map modify
+ * expressions return the bin's value (a map, or a list when the map is nested in a list). Valid
+ * map key types: String, Integer, byte[]. Maps support index (item offset) and rank (sorted value
+ * index), including negative indexing; use optional {@link com.aerospike.client.cdt.CTX} for
+ * nested maps/lists. For loop variables in filters use {@link Exp#mapLoopVar}, {@link Exp#stringLoopVar}
+ * with {@link LoopVarPart}.
  * <p>
- * Map modify expressions return the bin's value. This value will be a map except
- * when the map is nested within a list. In that case, a list is returned for the
- * map modify expression.
- * <p>
- * Valid map key types are:
+ * Index (item offset from start; negative = from end):
  * <ul>
- * <li>String</li>
- * <li>Integer</li>
- * <li>byte[]</li>
+ * <li>Index 0: first item; 4: fifth item; -1: last item; -3: third to last.</li>
+ * <li>Index 1 Count 2: second and third items; Index -3 Count 3: last three items.</li>
  * </ul>
- * <p>
- * The server will validate map key types in an upcoming release.
- * <p>
- * All maps maintain an index and a rank.  The index is the item offset from the start of the map,
- * for both unordered and ordered maps.  The rank is the sorted index of the value component.
- * Map supports negative indexing for index and rank.
- * <p>
- * Index examples:
+ * Rank (sorted index of value; negative = from highest):
  * <ul>
- * <li>Index 0: First item in map.</li>
- * <li>Index 4: Fifth item in map.</li>
- * <li>Index -1: Last item in map.</li>
- * <li>Index -3: Third to last item in map.</li>
- * <li>Index 1 Count 2: Second and third items in map.</li>
- * <li>Index -3 Count 3: Last three items in map.</li>
- * <li>Index -5 Count 4: Range between fifth to last item to second to last item inclusive.</li>
- * </ul>
- * <p>
- * Rank examples:
- * <ul>
- * <li>Rank 0: Item with lowest value rank in map.</li>
- * <li>Rank 4: Fifth lowest ranked item in map.</li>
- * <li>Rank -1: Item with highest ranked value in map.</li>
- * <li>Rank -3: Item with third highest ranked value in map.</li>
- * <li>Rank 1 Count 2: Second and third lowest ranked items in map.</li>
- * <li>Rank -3 Count 3: Top three ranked items in map.</li>
- * </ul>
- * <p>
- * Nested expressions are supported by optional CTX context arguments.  Example:
- * <ul>
- * <li>bin = {key1={key11=9,key12=4}, key2={key21=3,key22=5}}</li>
- * <li>Set map value to 11 for map key "key21" inside of map key "key2".</li>
- * <li>Get size of map key2.</li>
- * <li>MapExp.size(Exp.mapBin("bin"), CTX.mapKey(Value.get("key2"))</li>
- * <li>result = 2</li>
+ * <li>Rank 0: lowest ranked value; 4: fifth lowest; -1: highest ranked; -3: third highest.</li>
+ * <li>Rank 1 Count 2: second and third lowest; Rank -3 Count 3: top three ranked.</li>
  * </ul>
+ * <p>Filter by map, read with index/rank and nested CTX, and use a loop variable.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ *
+ * // Filter by map bin (key types: String, Integer, byte[])
+ * java.util.Map<String, Object> myMap = new java.util.HashMap<>();
+ * myMap.put("k", 1);
+ * Policy policy = new Policy();
+ * policy.filterExp = Exp.build(Exp.eq(Exp.mapBin("m"), Exp.val(myMap)));
+ * Record rec = client.get(policy, key);
+ *
+ * // Index: first (0), last (-1), range second+third (1, count 2), last three (-3, count 3)
+ * Exp byIndex0 = MapExp.getByIndex(MapReturnType.VALUE, Exp.Type.INT, Exp.val(0), Exp.mapBin("m"));
+ * Exp byIndexLast = MapExp.getByIndex(MapReturnType.VALUE, Exp.Type.INT, Exp.val(-1), Exp.mapBin("m"));
+ * Exp byIndexRange = MapExp.getByIndexRange(MapReturnType.KEY_VALUE, Exp.val(1), Exp.val(2), Exp.mapBin("m"));
+ * Exp lastThree = MapExp.getByIndexRange(MapReturnType.KEY_VALUE, Exp.val(-3), Exp.val(3), Exp.mapBin("m"));
+ *
+ * // Rank: lowest (0), highest (-1), second+third lowest (1, count 2), top three (-3, count 3)
+ * Exp byRank0 = MapExp.getByRank(MapReturnType.VALUE, Exp.Type.INT, Exp.val(0), Exp.mapBin("m"));
+ * Exp byRankLast = MapExp.getByRank(MapReturnType.VALUE, Exp.Type.INT, Exp.val(-1), Exp.mapBin("m"));
+ * Exp byRankRange = MapExp.getByRankRange(MapReturnType.KEY_VALUE, Exp.val(1), Exp.val(2), Exp.mapBin("m"));
+ * Exp topThree = MapExp.getByRankRange(MapReturnType.KEY_VALUE, Exp.val(-3), Exp.val(3), Exp.mapBin("m"));
+ *
+ * // Map modify (returns bin value)
+ * Expression exp = Exp.build(MapExp.removeByValue(MapReturnType.INVERTED, Exp.val(2), Exp.mapBin("m")));
+ * Record r = client.operate(null, key, ExpOperation.read("m", exp, ExpReadFlags.DEFAULT));
+ * java.util.Map<?, ?> result = r.getMap("m");
+ *
+ * // Nested map: size of map at key "key2" (bin = {key1={...}, key2={key21=3, key22=5}})
+ * Exp sizeExp = MapExp.size(Exp.mapBin("bin"), CTX.mapKey(com.aerospike.client.Value.get("key2")));
+ *
+ * // Loop variable in filter (e.g. with CTX.allChildrenWithFilter)
+ * Exp getPrice = MapExp.getByKey(MapReturnType.VALUE, Exp.Type.FLOAT, Exp.val("price"), Exp.mapLoopVar(LoopVarPart.VALUE));
+ * }</pre>
+ *
+ * @see Exp
+ * @see ListExp
+ * @see LoopVarPart
+ * @see com.aerospike.client.cdt.CTX
+ * @see com.aerospike.client.cdt.MapReturnType
  */
 public final class MapExp {
 	private static final int MODULE = 0;
@@ -113,7 +121,7 @@ public final class MapExp {
 	/**
 	 * Create expression that writes key/value item to a map bin. The 'bin' expression should either
 	 * reference an existing map bin or be a expression that returns a map.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Add entry{11,22} to existing map bin.
 	 * Expression e = Exp.build(MapExp.put(MapPolicy.Default, Exp.val(11), Exp.val(22), Exp.mapBin(binName)));
@@ -377,7 +385,7 @@ public static Exp removeByRankRange(int returnType, Exp rank, Exp count, Exp bin
 
 	/**
 	 * Create expression that returns list size.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Map bin "a" size > 7
 	 * Exp.gt(MapExp.size(Exp.mapBin("a")), Exp.val(7))
@@ -391,7 +399,7 @@ public static Exp size(Exp bin, CTX... ctx) {
 	/**
 	 * Create expression that selects map item identified by key and returns selected data
 	 * specified by returnType.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Map bin "a" contains key "B"
 	 * MapExp.getByKey(MapReturnType.EXISTS, Exp.Type.BOOL, Exp.val("B"), Exp.mapBin("a"))
@@ -470,7 +478,7 @@ public static Exp getByKeyRelativeIndexRange(int returnType, Exp key, Exp index,
 	/**
 	 * Create expression that selects map items identified by value and returns selected data
 	 * specified by returnType.
-	 *
+	 * <p>Example for this expression.</p>
 	 * <pre>{@code
 	 * // Map bin "a" contains value "BBB"
 	 * MapExp.getByValue(MapReturnType.EXISTS, Exp.val("BBB"), Exp.mapBin("a"))
diff --git a/client/src/com/aerospike/client/listener/AbortListener.java b/client/src/com/aerospike/client/listener/AbortListener.java
index 9ccabd7f2..20d39b84d 100644
--- a/client/src/com/aerospike/client/listener/AbortListener.java
+++ b/client/src/com/aerospike/client/listener/AbortListener.java
@@ -19,11 +19,29 @@
 import com.aerospike.client.AbortStatus;
 
 /**
- * Asynchronous result notifications for transaction aborts.
+ * Async callback for transaction abort; receives {@link com.aerospike.client.AbortStatus} on success.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#abort(com.aerospike.client.async.EventLoop, AbortListener, com.aerospike.client.Txn)}. Abort does not report failure via a separate callback.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.abort(loop, new AbortListener() {
+ *   public void onSuccess(AbortStatus status) { }
+ * }, txn);
+ * }</pre>
+ *
+ * @see com.aerospike.client.AbortStatus
+ * @see com.aerospike.client.IAerospikeClient#abort
+ * @see com.aerospike.client.Txn
  */
 public interface AbortListener {
 	/**
-	 * This method is called when the abort succeeded or will succeed.
+	 * Called when the abort completes successfully.
+	 * @param status abort status (must not be null)
 	 */
 	void onSuccess(AbortStatus status);
 }
diff --git a/client/src/com/aerospike/client/listener/BatchListListener.java b/client/src/com/aerospike/client/listener/BatchListListener.java
index a72e6746b..aad21ddf7 100644
--- a/client/src/com/aerospike/client/listener/BatchListListener.java
+++ b/client/src/com/aerospike/client/listener/BatchListListener.java
@@ -22,20 +22,35 @@
 import com.aerospike.client.BatchRead;
 
 /**
- * Asynchronous result notifications for batch get commands with variable bins per key.
- * The result is sent in a single list.
+ * Async callback for batch get with variable bins; receives a single list of {@link com.aerospike.client.BatchRead} results.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get} is null when the key is not found.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRead[] batchReads = new BatchRead[] { new BatchRead(new Key("ns", "set", "k1"), new String[] { "bin1" }) };
+ *
+ * client.get(loop, new BatchListListener() {
+ *   public void onSuccess(List records) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), batchReads);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
  */
 public interface BatchListListener {
 	/**
-	 * This method is called when the command completes successfully.
-	 *
-	 * @param records		record instances, {@link com.aerospike.client.BatchRecord#record}
-	 *						will be null if the key is not found
+	 * Called when the batch get completes; list order matches input BatchRead array.
+	 * @param records list of BatchRead; record is null when key not found
 	 */
 	public void onSuccess(List<BatchRead> records);
 
 	/**
-	 * This method is called when the command fails.
+	 * Called when the batch get fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/BatchOperateListListener.java b/client/src/com/aerospike/client/listener/BatchOperateListListener.java
index 0edf42005..bfac5c0f2 100644
--- a/client/src/com/aerospike/client/listener/BatchOperateListListener.java
+++ b/client/src/com/aerospike/client/listener/BatchOperateListListener.java
@@ -22,20 +22,35 @@
 import com.aerospike.client.BatchRecord;
 
 /**
- * Asynchronous result notifications for batch operate commands with variable operations.
+ * Async callback for batch operate with variable operations per key; receives a list of {@link com.aerospike.client.BatchRecord} and overall status.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchOperateListListener, com.aerospike.client.policy.BatchPolicy, java.util.List)}. Each record's result is in {@link com.aerospike.client.BatchRecord#record} (null on error).
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.operate(loop, new BatchOperateListListener() {
+ *   public void onSuccess(List records, boolean status) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), batchRecordList);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchOperateListListener, com.aerospike.client.policy.BatchPolicy, java.util.List)
  */
 public interface BatchOperateListListener {
 	/**
-	 * This method is called when the command completes successfully.
-	 *
-	 * @param records		record instances, {@link com.aerospike.client.BatchRecord#record}
-	 *						will be null if an error occurred for that key.
-	 * @param status		true if all records returned success.
+	 * Called when the batch operate completes; list order matches input.
+	 * @param records list of BatchRecord; record is null when that key had an error
+	 * @param status true if all records succeeded
 	 */
 	public void onSuccess(List<BatchRecord> records, boolean status);
 
 	/**
-	 * This method is called when the command fails.
+	 * Called when the batch operate fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/BatchRecordArrayListener.java b/client/src/com/aerospike/client/listener/BatchRecordArrayListener.java
index b13819507..cac8fd399 100644
--- a/client/src/com/aerospike/client/listener/BatchRecordArrayListener.java
+++ b/client/src/com/aerospike/client/listener/BatchRecordArrayListener.java
@@ -20,24 +20,38 @@
 import com.aerospike.client.BatchRecord;
 
 /**
- * Asynchronous result notifications for batch operate commands.
+ * Async callback for batch operate; receives full array of {@link com.aerospike.client.BatchRecord} and overall status.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchRecordArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.BatchRecord[])}. Records are in same order as input; check each {@link com.aerospike.client.BatchRecord#resultCode}.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRecord[] records = new BatchRecord[] { new BatchWrite(...) };
+ *
+ * client.operate(loop, new BatchRecordArrayListener() {
+ *   public void onSuccess(BatchRecord[] records, boolean status) { }
+ *   public void onFailure(BatchRecord[] records, AerospikeException e) { }
+ * }, new BatchPolicy(), records);
+ * }</pre>
+ *
+ * @see com.aerospike.client.BatchRecord
+ * @see com.aerospike.client.IAerospikeClient#operate(com.aerospike.client.async.EventLoop, BatchRecordArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.BatchRecord[])
  */
 public interface BatchRecordArrayListener {
 	/**
-	 * This method is called when the command completes successfully.
-	 * The returned record array is in positional order with the original key array order.
-	 *
-	 * @param records		record instances, always populated.
-	 * @param status		true if all records returned success.
+	 * Called when the batch operate completes; one entry per input record, in order.
+	 * @param records batch records, always populated (must not be null)
+	 * @param status true if all records succeeded
 	 */
 	public void onSuccess(BatchRecord[] records, boolean status);
 
 	/**
-	 * This method is called when one or more keys fail.
-	 *
-	 * @param records		record instances, always populated. {@link com.aerospike.client.BatchRecord#resultCode}
-	 * 						indicates if an error occurred for each record instance.
-	 * @param ae			error that occurred
+	 * Called when the batch fails; records may still be populated with per-key results.
+	 * @param records batch records (must not be null); check {@link com.aerospike.client.BatchRecord#resultCode}
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(BatchRecord[] records, AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java b/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java
index 44cfb4e43..1bbbc300c 100644
--- a/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/BatchRecordSequenceListener.java
@@ -20,26 +20,40 @@
 import com.aerospike.client.BatchRecord;
 
 /**
- * Asynchronous result notifications for batch operate commands.
- * The results are sent one record at a time.
+ * Async callback for batch operate; results delivered one {@link com.aerospike.client.BatchRecord} at a time via {@link #onRecord}, then {@link #onSuccess} or {@link #onFailure}.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#operate}. Order of onRecord is not guaranteed.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRecord[] records = new BatchRecord[] { new BatchWrite(...) };
+ *
+ * client.operate(loop, new BatchRecordSequenceListener() {
+ *   public void onRecord(BatchRecord record, int index) { }
+ *   public void onSuccess() { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), records);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#operate
  */
 public interface BatchRecordSequenceListener {
 	/**
-	 * This method is called when a record is received from the server.
-	 * The receive sequence is not ordered.
-	 *
-	 * @param record	record instance
-	 * @param index 	index offset into the original BatchRecord array.
+	 * Called for each batch record when received; order is not guaranteed.
+	 * @param record batch record (must not be null)
+	 * @param index index into the original BatchRecord array
 	 */
 	public void onRecord(BatchRecord record, int index);
 
-	/**
-	 * This method is called when the command completes successfully.
-	 */
+	/** Called when the batch operate completes successfully. */
 	public void onSuccess();
 
 	/**
-	 * This method is called when the command fails.
+	 * Called when the batch operate fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/BatchSequenceListener.java b/client/src/com/aerospike/client/listener/BatchSequenceListener.java
index 401b617bc..e5387b961 100644
--- a/client/src/com/aerospike/client/listener/BatchSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/BatchSequenceListener.java
@@ -20,26 +20,39 @@
 import com.aerospike.client.BatchRead;
 
 /**
- * Asynchronous result notifications for batch get commands with variable bins per key.
- * The results are sent one batch record at a time.
+ * Async callback for batch get with variable bins; results delivered one {@link com.aerospike.client.BatchRead} at a time via {@link #onRecord}, then {@link #onSuccess} or {@link #onFailure}.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get}. Order of onRecord is not guaranteed; {@link com.aerospike.client.BatchRead#record} is null when key is not found.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * BatchRead[] batchReads = new BatchRead[] { new BatchRead(new Key("ns", "set", "k1"), new String[] { "bin1" }) };
+ *
+ * client.get(loop, new BatchSequenceListener() {
+ *   public void onRecord(BatchRead record) { }
+ *   public void onSuccess() { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), batchReads);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
  */
 public interface BatchSequenceListener {
 	/**
-	 * This method is called when an asynchronous batch record is received from the server.
-	 * The receive sequence is not ordered.
-	 *
-	 * @param record	record instance, {@link com.aerospike.client.BatchRecord#record}
-	 *					will be null if the key is not found
+	 * Called for each batch read when received; order is not guaranteed.
+	 * @param record batch read; {@link com.aerospike.client.BatchRead#record} is null if key not found
 	 */
 	public void onRecord(BatchRead record);
 
-	/**
-	 * This method is called when the command completes successfully.
-	 */
+	/** Called when the batch get completes successfully. */
 	public void onSuccess();
 
 	/**
-	 * This method is called when the command fails.
+	 * Called when the batch get fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/ClusterStatsListener.java b/client/src/com/aerospike/client/listener/ClusterStatsListener.java
index 45356638c..b590315e2 100644
--- a/client/src/com/aerospike/client/listener/ClusterStatsListener.java
+++ b/client/src/com/aerospike/client/listener/ClusterStatsListener.java
@@ -20,16 +20,35 @@
 import com.aerospike.client.cluster.ClusterStats;
 
 /**
- * Asynchronous result notifications for cluster statistics.
+ * Async callback for cluster statistics; receives {@link com.aerospike.client.cluster.ClusterStats} or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#getClusterStats}.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.getClusterStats(loop, new ClusterStatsListener() {
+ *   public void onSuccess(ClusterStats stats) { }
+ *   public void onFailure(AerospikeException e) { }
+ * });
+ * }</pre>
+ *
+ * @see com.aerospike.client.cluster.ClusterStats
+ * @see com.aerospike.client.IAerospikeClient#getClusterStats
  */
 public interface ClusterStatsListener {
 	/**
-	 * This method is called when command completes successfully.
+	 * Called when the cluster stats request completes successfully.
+	 * @param stats cluster statistics (must not be null)
 	 */
 	public void onSuccess(ClusterStats stats);
 
 	/**
-	 * This method is called when command fails.
+	 * Called when the cluster stats request fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/CommitListener.java b/client/src/com/aerospike/client/listener/CommitListener.java
index 358f89cde..724773666 100644
--- a/client/src/com/aerospike/client/listener/CommitListener.java
+++ b/client/src/com/aerospike/client/listener/CommitListener.java
@@ -20,16 +20,36 @@
 import com.aerospike.client.CommitStatus;
 
 /**
- * Asynchronous result notifications for transaction commits.
+ * Async callback for transaction commit; receives {@link com.aerospike.client.CommitStatus} or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#commit}
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.commit(loop, new CommitListener() {
+ *   public void onSuccess(CommitStatus status) { }
+ *   public void onFailure(AerospikeException.Commit e) { }
+ * }, new CommitPolicy(), txn);
+ * }</pre>
+ *
+ * @see com.aerospike.client.CommitStatus
+ * @see com.aerospike.client.IAerospikeClient#commit
+ * @see com.aerospike.client.Txn
  */
 public interface CommitListener {
 	/**
-	 * This method is called when the records are verified and the commit succeeded or will succeed.
+	 * Called when the commit completes (verified or will succeed).
+	 * @param status commit status (must not be null)
 	 */
 	void onSuccess(CommitStatus status);
 
 	/**
-	 * This method is called when the commit fails.
+	 * Called when the commit fails.
+	 * @param ae commit exception cause of failure wrapped into Aerospike exception
 	 */
 	void onFailure(AerospikeException.Commit ae);
 }
diff --git a/client/src/com/aerospike/client/listener/DeleteListener.java b/client/src/com/aerospike/client/listener/DeleteListener.java
index 1f345f94a..0ebe67fe2 100644
--- a/client/src/com/aerospike/client/listener/DeleteListener.java
+++ b/client/src/com/aerospike/client/listener/DeleteListener.java
@@ -20,19 +20,35 @@
 import com.aerospike.client.Key;
 
 /**
- * Asynchronous result notifications for delete commands.
+ * Async callback for delete; receives key, whether record existed, or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#delete}
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.delete(loop, new DeleteListener() {
+ *   public void onSuccess(Key key, boolean existed) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new WritePolicy(), key);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#delete
  */
 public interface DeleteListener {
 	/**
-	 * This method is called when an asynchronous delete command completes successfully.
-	 *
-	 * @param key		unique record identifier
-	 * @param existed	whether record existed on server before deletion
+	 * Called when the delete completes successfully.
+	 * @param key record key (must not be null)
+	 * @param existed true if the record existed before deletion
 	 */
 	public void onSuccess(Key key, boolean existed);
 
 	/**
-	 * This method is called when an asynchronous delete command fails.
+	 * Called when the delete fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/ExecuteListener.java b/client/src/com/aerospike/client/listener/ExecuteListener.java
index 6eea971e6..9670cb0ed 100644
--- a/client/src/com/aerospike/client/listener/ExecuteListener.java
+++ b/client/src/com/aerospike/client/listener/ExecuteListener.java
@@ -20,19 +20,35 @@
 import com.aerospike.client.Key;
 
 /**
- * Asynchronous result notifications for execute commands.
+ * Async callback for execute (UDF); receives key, return value, or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#execute}
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.execute(loop, new ExecuteListener() {
+ *   public void onSuccess(Key key, Object obj) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new Policy(), key, "module", "function", null);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#execute
  */
 public interface ExecuteListener {
 	/**
-	 * This method is called when an asynchronous execute command completes successfully.
-	 *
-	 * @param key	unique record identifier
-	 * @param obj	returned object
+	 * Called when the execute completes successfully.
+	 * @param key record key (must not be null)
+	 * @param obj value returned by the UDF, or null
 	 */
 	public void onSuccess(Key key, Object obj);
 
 	/**
-	 * This method is called when an asynchronous execute command fails.
+	 * Called when the execute fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/ExistsArrayListener.java b/client/src/com/aerospike/client/listener/ExistsArrayListener.java
index b5b3dc486..d83404d6f 100644
--- a/client/src/com/aerospike/client/listener/ExistsArrayListener.java
+++ b/client/src/com/aerospike/client/listener/ExistsArrayListener.java
@@ -20,23 +20,37 @@
 import com.aerospike.client.Key;
 
 /**
- * Asynchronous result notifications for batch exists commands.
- * The result is sent in a single array.
+ * Async callback for batch exists; receives keys and existence flags in one array (same order as input keys).
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#exists(com.aerospike.client.async.EventLoop, ExistsArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.Key[])}.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1") };
+ *
+ * client.exists(loop, new ExistsArrayListener() {
+ *   public void onSuccess(Key[] keys, boolean[] exists) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), keys);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#exists(com.aerospike.client.async.EventLoop, ExistsArrayListener, com.aerospike.client.policy.BatchPolicy, com.aerospike.client.Key[])
+ * @see com.aerospike.client.AerospikeException.BatchExists
  */
 public interface ExistsArrayListener {
 	/**
-	 * This method is called when the command completes successfully.
-	 * The returned boolean array is in positional order with the original key array order.
-	 *
-	 * @param keys		unique record identifiers
-	 * @param exists	whether keys exists on server
+	 * Called when the batch exists completes; arrays are in same order as the key array.
+	 * @param keys original keys (must not be null)
+	 * @param exists existence per key (must not be null)
 	 */
 	public void onSuccess(Key[] keys, boolean[] exists);
 
 	/**
-	 * This method is called when the command fails. The AerospikeException is likely to be
-	 * {@link com.aerospike.client.AerospikeException.BatchExists} which contains results
-	 * for keys that did complete.
+	 * Called when the batch fails; may be {@link com.aerospike.client.AerospikeException.BatchExists} with partial results.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/ExistsListener.java b/client/src/com/aerospike/client/listener/ExistsListener.java
index 81354007a..41486e24d 100644
--- a/client/src/com/aerospike/client/listener/ExistsListener.java
+++ b/client/src/com/aerospike/client/listener/ExistsListener.java
@@ -20,19 +20,36 @@
 import com.aerospike.client.Key;
 
 /**
- * Asynchronous result notifications for exists commands.
+ * Async callback for exists; receives key, existence flag, or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#exists} or untouched
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.exists(loop, new ExistsListener() {
+ *   public void onSuccess(Key key, boolean exists) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new Policy(), key);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#exists
+ * @see com.aerospike.client.IAerospikeClient#touched
  */
 public interface ExistsListener {
 	/**
-	 * This method is called when an asynchronous exists command completes successfully.
-	 *
-	 * @param key		unique record identifier
-	 * @param exists	whether key exists on server
+	 * Called when the exists check completes successfully.
+	 * @param key record key (must not be null)
+	 * @param exists true if the record exists on the server
 	 */
 	public void onSuccess(Key key, boolean exists);
 
 	/**
-	 * This method is called when an asynchronous exists command fails.
+	 * Called when the exists check fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/ExistsSequenceListener.java b/client/src/com/aerospike/client/listener/ExistsSequenceListener.java
index ee54acbbc..92b81171c 100644
--- a/client/src/com/aerospike/client/listener/ExistsSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/ExistsSequenceListener.java
@@ -20,26 +20,40 @@
 import com.aerospike.client.Key;
 
 /**
- * Asynchronous result notifications for batch exists commands.
- * The results are sent one record at a time.
+ * Async callback for batch exists; results delivered one key at a time via {@link #onExists}, then {@link #onSuccess} or {@link #onFailure}.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#exists}. Order of onExists is not guaranteed.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1") };
+ *
+ * client.exists(loop, new ExistsSequenceListener() {
+ *   public void onExists(Key key, boolean exists) { }
+ *   public void onSuccess() { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), keys);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#exists
  */
 public interface ExistsSequenceListener {
 	/**
-	 * This method is called when an asynchronous batch exists result is received from the server.
-	 * The receive sequence is not ordered.
-	 *
-	 * @param key		unique record identifier
-	 * @param exists	whether key exists on server
+	 * Called for each key when its exists result is received; order is not guaranteed.
+	 * @param key record key (must not be null)
+	 * @param exists true if the record exists on the server
 	 */
 	public void onExists(Key key, boolean exists);
 
-	/**
-	 * This method is called when the asynchronous batch exists command completes.
-	 */
+	/** Called when the batch exists completes successfully. */
 	public void onSuccess();
 
 	/**
-	 * This method is called when an asynchronous batch exists command fails.
+	 * Called when the batch exists fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/IndexListener.java b/client/src/com/aerospike/client/listener/IndexListener.java
index c15ebb8eb..5bcea9d84 100644
--- a/client/src/com/aerospike/client/listener/IndexListener.java
+++ b/client/src/com/aerospike/client/listener/IndexListener.java
@@ -20,18 +20,39 @@
 import com.aerospike.client.async.AsyncIndexTask;
 
 /**
- * Asynchronous result notifications for create/drop index commands.
+ * Async callback for create/drop index; receives {@link com.aerospike.client.async.AsyncIndexTask} to poll status or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#createIndex} and dropIndex overloads. Use the task in onSuccess to call {@link com.aerospike.client.async.AsyncIndexTask#queryStatus} for completion.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.createIndex(loop, new InfoPolicy(), "ns", "set", "idx1", "bin1", IndexType.STRING, new IndexListener() {
+ *   public void onSuccess(AsyncIndexTask task) {
+ *     task.queryStatus(loop, policy, node, new TaskStatusListener() { ... });
+ *   }
+ *   public void onFailure(AerospikeException e) { }
+ * });
+ * }</pre>
+ *
+ * @see com.aerospike.client.async.AsyncIndexTask
+ * @see TaskStatusListener
+ * @see com.aerospike.client.IAerospikeClient#createIndex
+ * @see com.aerospike.client.IAerospikeClient#dropIndex
  */
 public interface IndexListener {
 	/**
-	 * This method is called when an asynchronous command completes successfully.
-	 *
-	 * @param indexTask		task monitor that can be used to query for index command completion.
+	 * Called when the create/drop index request is accepted; use the task to poll completion.
+	 * @param indexTask task monitor for querying index status (must not be null)
 	 */
 	void onSuccess(AsyncIndexTask indexTask);
 
 	/**
-	 * This method is called when an asynchronous command fails.
+	 * Called when the create/drop index request fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/InfoListener.java b/client/src/com/aerospike/client/listener/InfoListener.java
index f023b71cb..681fd3268 100644
--- a/client/src/com/aerospike/client/listener/InfoListener.java
+++ b/client/src/com/aerospike/client/listener/InfoListener.java
@@ -21,20 +21,35 @@
 import com.aerospike.client.AerospikeException;
 
 /**
- * Asynchronous info command result notification.
+ * Async callback for info command; receives a map of info key-value pairs or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#info}
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Node node = client.getNodes()[0];
+ *
+ * client.info(loop, new InfoListener() {
+ *   public void onSuccess(Map map) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new InfoPolicy(), node, "build");
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#info
  */
 public interface InfoListener {
 	/**
-	 * This method is called when an asynchronous info command completes successfully.
-	 *
-	 * @param map			map of info command keys and result values.
+	 * Called when the info command completes successfully.
+	 * @param map map of info keys to result values (must not be null)
 	 */
 	public void onSuccess(Map<String,String> map);
 
 	/**
-	 * This method is called when an asynchronous info command fails.
-	 *
-	 * @param ae			error that occurred
+	 * Called when the info command fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/RecordArrayListener.java b/client/src/com/aerospike/client/listener/RecordArrayListener.java
index d3132c854..488873ab9 100644
--- a/client/src/com/aerospike/client/listener/RecordArrayListener.java
+++ b/client/src/com/aerospike/client/listener/RecordArrayListener.java
@@ -21,23 +21,37 @@
 import com.aerospike.client.Record;
 
 /**
- * Asynchronous result notifications for batch get commands.
- * The result is sent in a single array.
+ * Async callback for batch get; receives keys and records in one array (same order as input keys).
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get}. Records align by index with keys; null record means key not found.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Key[] keys = new Key[] { new Key("ns", "set", "k1") };
+ *
+ * client.get(loop, new RecordArrayListener() {
+ *   public void onSuccess(Key[] keys, Record[] records) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new BatchPolicy(), keys);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
+ * @see com.aerospike.client.AerospikeException.BatchRecords
  */
 public interface RecordArrayListener {
 	/**
-	 * This method is called when the command completes successfully.
-	 * The returned record array is in positional order with the original key array order.
-	 *
-	 * @param keys			unique record identifiers
-	 * @param records		record instances, an instance will be null if the key is not found
+	 * Called when the batch get completes; arrays are in same order as the key array.
+	 * @param keys original keys (must not be null)
+	 * @param records records; null at index i means key i was not found
 	 */
 	public void onSuccess(Key[] keys, Record[] records);
 
 	/**
-	 * This method is called when the command fails. The AerospikeException is likely to be
-	 * {@link com.aerospike.client.AerospikeException.BatchRecords} which contains results
-	 * for keys that did complete.
+	 * Called when the batch fails; may be {@link com.aerospike.client.AerospikeException.BatchRecords} with partial results.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/RecordListener.java b/client/src/com/aerospike/client/listener/RecordListener.java
index d75f5904a..8246593e6 100644
--- a/client/src/com/aerospike/client/listener/RecordListener.java
+++ b/client/src/com/aerospike/client/listener/RecordListener.java
@@ -21,19 +21,38 @@
 import com.aerospike.client.Record;
 
 /**
- * Asynchronous result notifications for get or operate commands.
+ * Async callback for single-key get and operate; receives one record or failure.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#get} or operate overloads. Called once per key with the record (or null if not found) or with an exception.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.get(loop, new Policy(), new RecordListener() {
+ *   public void onSuccess(Key key, Record record) {
+ *     if (record != null) { Object v = record.getValue("bin"); }
+ *   }
+ *   public void onFailure(AerospikeException e) { }
+ * }, key);
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#get
+ * @see com.aerospike.client.IAerospikeClient#operate
  */
 public interface RecordListener {
 	/**
-	 * This method is called when an asynchronous get or operate command completes successfully.
-	 *
-	 * @param key			unique record identifier
-	 * @param record		record instance if found, otherwise null
+	 * Called when the get or operate completes successfully.
+	 * @param key record key (must not be null)
+	 * @param record record if found, otherwise null
 	 */
 	public void onSuccess(Key key, Record record);
 
 	/**
-	 * This method is called when an asynchronous get or operate command fails.
+	 * Called when the get or operate fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/RecordSequenceListener.java b/client/src/com/aerospike/client/listener/RecordSequenceListener.java
index ec56e342c..a48a196df 100644
--- a/client/src/com/aerospike/client/listener/RecordSequenceListener.java
+++ b/client/src/com/aerospike/client/listener/RecordSequenceListener.java
@@ -21,36 +21,46 @@
 import com.aerospike.client.Record;
 
 /**
- * Asynchronous result notifications for batch get and scan/query commands.
- * The results are sent one record at a time.
+ * Asynchronous callback for batch get and scan/query; results are delivered one record at a time via {@link #onRecord}, then {@link #onSuccess} or {@link #onFailure}.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#query} or {@link com.aerospike.client.AerospikeClient#get} async overloads. For scan/query, throw {@link com.aerospike.client.AerospikeException.QueryTerminated} or {@link com.aerospike.client.AerospikeException.ScanTerminated} to abort; the exception is reported in {@link #onFailure}.
+ *
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * client.query(loop, new RecordSequenceListener() {
+ *   public void onRecord(Key key, Record record) {
+ *     if (record != null) { Object v = record.getValue("mybin"); }
+ *   }
+ *   public void onSuccess() { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, null, stmt);
+ * }</pre>
+ *
+ * @see #onSuccess
+ * @see #onFailure(AerospikeException)
+ * @see com.aerospike.client.AerospikeClient#query
+ * @see com.aerospike.client.AerospikeClient#get
  */
 public interface RecordSequenceListener {
 	/**
-	 * This method is called when an asynchronous record is received from the server.
-	 * The receive sequence is not ordered.
-	 * <p>
-	 * If this listener is used in a scan/query command, The user may throw a
-	 * {@link com.aerospike.client.AerospikeException.QueryTerminated AerospikeException.QueryTerminated}
-	 * exception if the command should be aborted. If any exception is thrown, parallel command threads
-	 * to other nodes will also be terminated and the exception will be propagated back through the
-	 * onFailure() call.
-	 * <p>
-	 * If this listener is used in a batch command, an user thrown exception will terminate the batch
-	 * to the current node, but parallel batch command threads to other nodes will continue to run.
+	 * Called when an asynchronous record is received; order is not guaranteed. For scan/query, throw QueryTerminated or ScanTerminated to abort (reported in onFailure). For batch, a thrown exception stops only the current node.
 	 *
-	 * @param key					unique record identifier
-	 * @param record				record instance, will be null if the key is not found
-	 * @throws AerospikeException	if error occurs or scan should be terminated.
+	 * @param key    unique record identifier; never null
+	 * @param record record instance; null if the key is not found
+	 * @throws AerospikeException when an error occurs or the scan/query should be terminated (e.g. throw ScanTerminated or QueryTerminated to abort).
 	 */
 	public void onRecord(Key key, Record record) throws AerospikeException;
 
-	/**
-	 * This method is called when the asynchronous batch get or scan command completes.
-	 */
+	/** Called when the asynchronous batch get or scan/query completes successfully. */
 	public void onSuccess();
 
-	/**
-	 * This method is called when an asynchronous batch get or scan command fails.
-	 */
+	/** Called when the asynchronous batch get or scan/query fails; receives the exception. */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/TaskStatusListener.java b/client/src/com/aerospike/client/listener/TaskStatusListener.java
index f3aed9ac1..bcd12f765 100644
--- a/client/src/com/aerospike/client/listener/TaskStatusListener.java
+++ b/client/src/com/aerospike/client/listener/TaskStatusListener.java
@@ -19,18 +19,32 @@
 import com.aerospike.client.AerospikeException;
 
 /**
- * Asynchronous result notifications for index status command.
+ * Async callback for index task status (e.g. from {@link com.aerospike.client.async.AsyncIndexTask#queryStatus}); receives load percentage or exception.
+ * <p>
+ * Pass to {@link com.aerospike.client.async.AsyncIndexTask#queryStatus}. Status 100 means complete; see {@link com.aerospike.client.task.Task}.
+ * <pre>{@code
+ * task.queryStatus(loop, new InfoPolicy(), node, new TaskStatusListener() {
+ *   public void onSuccess(int status) {
+ *     if (status == 100) { }
+ *   }
+ *   public void onFailure(AerospikeException e) { }
+ * });
+ * }</pre>
+ *
+ * @see com.aerospike.client.async.AsyncIndexTask#queryStatus
+ * @see IndexListener
+ * @see com.aerospike.client.task.Task
  */
 public interface TaskStatusListener {
 	/**
-	 * This method is called when an asynchronous command completes successfully.
-	 *
-	 * @param status	task status (see {@link com.aerospike.client.task.Task})
+	 * Called when the asynchronous command completes successfully
+	 * @param status  task status see {@link com.aerospike.client.task.Task}
 	 */
 	void onSuccess(int status);
 
 	/**
-	 * This method is called when an asynchronous command fails.
+	 * Called when the asynchronous command fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/listener/WriteListener.java b/client/src/com/aerospike/client/listener/WriteListener.java
index 49b9cd09f..f487bedcb 100644
--- a/client/src/com/aerospike/client/listener/WriteListener.java
+++ b/client/src/com/aerospike/client/listener/WriteListener.java
@@ -20,18 +20,35 @@
 import com.aerospike.client.Key;
 
 /**
- * Asynchronous result notifications for put, append, prepend, add, delete and touch commands.
+ * Async callback for put, append, prepend, add, touch; receives key on success or exception on failure.
+ * <p>
+ * Pass to {@link com.aerospike.client.IAerospikeClient#put} and other write overloads.
+ * <pre>{@code
+ * EventLoops eventLoops = new NioEventLoops(4);
+ * ClientPolicy clientPolicy = new ClientPolicy();
+ * clientPolicy.eventLoops = eventLoops;
+ * IAerospikeClient client = new AerospikeClient(clientPolicy, "localhost", 3000);
+ * EventLoop loop = eventLoops.next();
+ *
+ * client.put(loop, new WriteListener() {
+ *   public void onSuccess(Key key) { }
+ *   public void onFailure(AerospikeException e) { }
+ * }, new WritePolicy(), key, new Bin("bin", "value"));
+ * }</pre>
+ *
+ * @see com.aerospike.client.IAerospikeClient#put
+ * @see com.aerospike.client.IAerospikeClient#delete
  */
 public interface WriteListener {
 	/**
 	 * This method is called when an asynchronous write command completes successfully.
-	 *
-	 * @param key		unique record identifier
+	 * @param key unique record identifier (must not be null)
 	 */
 	public void onSuccess(Key key);
 
 	/**
 	 * This method is called when an asynchronous write command fails.
+	 * @param ae exception cause of failure wrapped into Aerospike exception
 	 */
 	public void onFailure(AerospikeException ae);
 }
diff --git a/client/src/com/aerospike/client/operation/BitOperation.java b/client/src/com/aerospike/client/operation/BitOperation.java
index 5eba701a5..a87d5f485 100644
--- a/client/src/com/aerospike/client/operation/BitOperation.java
+++ b/client/src/com/aerospike/client/operation/BitOperation.java
@@ -22,13 +22,29 @@
 import com.aerospike.client.util.Packer;
 
 /**
- * Bit operations. Create bit operations used by client operate command.
- * Offset orientation is left-to-right.  Negative offsets are supported.
+ * Bit (byte[]) operations for the client operate command. Offset orientation is left-to-right, Negative offsets are supported.
  * If the offset is negative, the offset starts backwards from end of the bitmap.
  * If an offset is out of bounds, a parameter error will be returned.
  * <p>
- * Bit operations on bitmap items nested in lists/maps are not currently
- * supported by the server.
+ * Use with {@link com.aerospike.client.AerospikeClient#operate}. Nested bitmaps in list/map bins are not supported by the server. For expression-based bit ops in filters, see {@link com.aerospike.client.exp.BitExp}.
+ * <p>Resize a bit bin and read bytes with operate.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * client.operate(null, key,
+ *     BitOperation.resize(BitPolicy.Default, "bits", 4, BitResizeFlags.DEFAULT),
+ *     BitOperation.get("bits", 0, 4));
+ * Record rec = client.get(null, key);
+ * byte[] bits = rec.getBytes("bits");
+ * client.close();
+ * }</pre>
+ *
+ * @see BitPolicy
+ * @see BitResizeFlags
+ * @see BitWriteFlags
+ * @see BitOverflowAction
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.exp.BitExp
  */
 public final class BitOperation {
 	private static final int RESIZE = 0;
diff --git a/client/src/com/aerospike/client/operation/BitOverflowAction.java b/client/src/com/aerospike/client/operation/BitOverflowAction.java
index 1de69130b..e99d1c9c7 100644
--- a/client/src/com/aerospike/client/operation/BitOverflowAction.java
+++ b/client/src/com/aerospike/client/operation/BitOverflowAction.java
@@ -17,7 +17,11 @@
 package com.aerospike.client.operation;
 
 /**
- * Action to take when bitwise add/subtract results in overflow/underflow.
+ * Action when bit add/subtract overflows or underflows; used in {@link BitOperation} integer bit ops.
+ * <p>
+ * Pass to {@link BitOperation#add}, {@link BitOperation#subtract}, {@link BitOperation#setInt}, {@link BitOperation#getInt}.
+ *
+ * @see BitOperation
  */
 public enum BitOverflowAction {
 	/**
diff --git a/client/src/com/aerospike/client/operation/BitPolicy.java b/client/src/com/aerospike/client/operation/BitPolicy.java
index 13f3d67a4..e89a32753 100644
--- a/client/src/com/aerospike/client/operation/BitPolicy.java
+++ b/client/src/com/aerospike/client/operation/BitPolicy.java
@@ -17,12 +17,24 @@
 package com.aerospike.client.operation;
 
 /**
- * Bit operation policy.
+ * Policy for bit (byte[]) operations; holds {@link BitWriteFlags} used by {@link BitOperation}.
+ * <p>
+ * Pass to {@link BitOperation#resize}, {@link BitOperation#insert}, {@link BitOperation#set}, and other BitOperation methods.
+ * <p>Use BitPolicy with resize and set.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BitPolicy policy = BitPolicy.Default;
+ * client.operate(null, key, BitOperation.resize(policy, "bits", 8, BitResizeFlags.DEFAULT));
+ *
+ * BitPolicy createOnly = new BitPolicy(BitWriteFlags.CREATE_ONLY);
+ * client.operate(null, key, BitOperation.set(createOnly, "bits", 0, new byte[] { 1, 2, 3 }));
+ * }</pre>
+ *
+ * @see BitOperation
+ * @see BitWriteFlags
  */
 public final class BitPolicy {
-	/**
-	 * Default byte[] with normal bin write semantics.
-	 */
+	/** Default policy with normal create/update semantics. */
 	public static final BitPolicy Default = new BitPolicy();
 
 	public final int flags;
diff --git a/client/src/com/aerospike/client/operation/BitResizeFlags.java b/client/src/com/aerospike/client/operation/BitResizeFlags.java
index 3e6231bef..7fbac8ab1 100644
--- a/client/src/com/aerospike/client/operation/BitResizeFlags.java
+++ b/client/src/com/aerospike/client/operation/BitResizeFlags.java
@@ -17,7 +17,11 @@
 package com.aerospike.client.operation;
 
 /**
- * Bitwise operation flags for resize.
+ * Flags for {@link BitOperation#resize}; control where bytes are added/removed and size direction.
+ * <p>
+ * Combine with BITWISE OR when needed. Pass to {@link BitOperation#resize(BitPolicy, String, int, int)}.
+ *
+ * @see BitOperation#resize
  */
 public final class BitResizeFlags {
 	/**
diff --git a/client/src/com/aerospike/client/operation/BitWriteFlags.java b/client/src/com/aerospike/client/operation/BitWriteFlags.java
index 6b8e90810..1cf6777ec 100644
--- a/client/src/com/aerospike/client/operation/BitWriteFlags.java
+++ b/client/src/com/aerospike/client/operation/BitWriteFlags.java
@@ -17,11 +17,17 @@
 package com.aerospike.client.operation;
 
 /**
- * Bitwise operation policy write bit flags. Use BITWISE OR to combine flags. Example:
- * 
- * <pre>{@code 
+ * Write flags for bit operations; combine with BITWISE OR and pass to {@link BitPolicy}.
+ * <p>
+ * <p>Combine bit write flags and pass to BitPolicy.</p>
+ * <pre>{@code
  * int flags = BitWriteFlags.NO_FAIL | BitWriteFlags.PARTIAL;
+ * BitPolicy policy = new BitPolicy(flags);
+ * client.operate(null, key, BitOperation.set(policy, "bits", 0, value));
  * }</pre>
+ *
+ * @see BitPolicy
+ * @see BitOperation
  */
 public final class BitWriteFlags {
 	/**
diff --git a/client/src/com/aerospike/client/operation/HLLOperation.java b/client/src/com/aerospike/client/operation/HLLOperation.java
index a9acd2d85..afeb08bd0 100644
--- a/client/src/com/aerospike/client/operation/HLLOperation.java
+++ b/client/src/com/aerospike/client/operation/HLLOperation.java
@@ -24,10 +24,25 @@
 import com.aerospike.client.util.Pack;
 
 /**
- * HyperLogLog (HLL) operations.
+ * HyperLogLog (HLL) operations for the client operate command; init, add, count, union, similarity, etc.
  * <p>
- * HyperLogLog operations on HLL items nested in lists/maps are not currently
- * supported by the server.
+ * Use with {@link com.aerospike.client.AerospikeClient#operate}. HLL bins nested in list/map are not supported by the server. For expression-based HLL in filters, see {@link com.aerospike.client.exp.HLLExp}.
+ * <p>Init and add to an HLL bin then count.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Key key = new Key("ns", "set", "mykey");
+ * client.operate(null, key,
+ *     HLLOperation.init(HLLPolicy.Default, "hll", 14),
+ *     HLLOperation.add(HLLPolicy.Default, "hll", listOfValues));
+ * Record rec = client.operate(null, key, HLLOperation.count("hll"));
+ * long count = rec.getLong("hll");
+ * client.close();
+ * }</pre>
+ *
+ * @see HLLPolicy
+ * @see HLLWriteFlags
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see com.aerospike.client.exp.HLLExp
  */
 public final class HLLOperation {
 	private static final int INIT = 0;
diff --git a/client/src/com/aerospike/client/operation/HLLPolicy.java b/client/src/com/aerospike/client/operation/HLLPolicy.java
index 7100a6c4b..5d11b30ca 100644
--- a/client/src/com/aerospike/client/operation/HLLPolicy.java
+++ b/client/src/com/aerospike/client/operation/HLLPolicy.java
@@ -17,12 +17,25 @@
 package com.aerospike.client.operation;
 
 /**
- * HyperLogLog operation policy.
+ * Policy for HyperLogLog operations; holds {@link HLLWriteFlags} used by {@link HLLOperation}.
+ * <p>
+ * Pass to {@link HLLOperation#init}, {@link HLLOperation#add}, and other HLLOperation methods.
+ * <p>Use HLLPolicy with init and add.</p>
+ * <pre>{@code
+ * HLLPolicy policy = HLLPolicy.Default;
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * client.operate(null, key, HLLOperation.init(policy, "hll", 14));
+ * client.operate(null, key, HLLOperation.add(policy, "hll", valueList));
+ *
+ * HLLPolicy createOnly = new HLLPolicy(HLLWriteFlags.CREATE_ONLY);
+ * client.operate(null, key, HLLOperation.init(createOnly, "hll", 12));
+ * }</pre>
+ *
+ * @see HLLOperation
+ * @see HLLWriteFlags
  */
 public final class HLLPolicy {
-	/**
-	 * Default HLL bin write semantics.
-	 */
+	/** Default policy with normal create/update semantics. */
 	public static final HLLPolicy Default = new HLLPolicy();
 
 	public final int flags;
diff --git a/client/src/com/aerospike/client/operation/HLLWriteFlags.java b/client/src/com/aerospike/client/operation/HLLWriteFlags.java
index 171148ea7..eafa72f17 100644
--- a/client/src/com/aerospike/client/operation/HLLWriteFlags.java
+++ b/client/src/com/aerospike/client/operation/HLLWriteFlags.java
@@ -17,11 +17,18 @@
 package com.aerospike.client.operation;
 
 /**
- * HyperLogLog operation policy write bit flags. Use BITWISE OR to combine flags. Example:
- * 
- * <pre>{@code 
+ * Write flags for HyperLogLog operations; combine with BITWISE OR and pass to {@link HLLPolicy}.
+ * <p>
+ * <p>Combine HLL write flags and pass to HLLPolicy.</p>
+ * <pre>{@code
  * int flags = HLLWriteFlags.CREATE_ONLY | HLLWriteFlags.NO_FAIL;
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * HLLPolicy policy = new HLLPolicy(flags);
+ * client.operate(null, key, HLLOperation.init(policy, "hll", 14));
  * }</pre>
+ *
+ * @see HLLPolicy
+ * @see HLLOperation
  */
 public final class HLLWriteFlags {
 	/**
diff --git a/client/src/com/aerospike/client/policy/AdminPolicy.java b/client/src/com/aerospike/client/policy/AdminPolicy.java
index 9d43ed6ca..c51a58dbb 100644
--- a/client/src/com/aerospike/client/policy/AdminPolicy.java
+++ b/client/src/com/aerospike/client/policy/AdminPolicy.java
@@ -17,7 +17,21 @@
 package com.aerospike.client.policy;
 
 /**
- * Policy attributes used for user administration commands.
+ * Policy for admin commands (create/drop user/role, grant/revoke, etc.): socket timeout.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#createUser}, {@link com.aerospike.client.AerospikeClient#createRole}, and other admin methods. Default timeout 0 (no timeout).
+ *
+ * <p><b>Example:</b>
+ * <p>Create a user with a 5-second timeout for the admin command.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * AdminPolicy ap = new AdminPolicy();
+ * ap.timeout = 5000;
+ * client.createUser(ap, "jdoe", "secret", java.util.Collections.emptyList());
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient#createUser
+ * @see com.aerospike.client.AerospikeClient#createRole
  */
 public final class AdminPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/AuthMode.java b/client/src/com/aerospike/client/policy/AuthMode.java
index 93a1e0ae8..fbd343da1 100644
--- a/client/src/com/aerospike/client/policy/AuthMode.java
+++ b/client/src/com/aerospike/client/policy/AuthMode.java
@@ -17,7 +17,9 @@
 package com.aerospike.client.policy;
 
 /**
- * Authentication mode.
+ * Authentication mode (internal, external, PKI). Set on {@link ClientPolicy#authMode} to match server configuration.
+ *
+ * @see ClientPolicy#authMode
  */
 public enum AuthMode {
 	/**
diff --git a/client/src/com/aerospike/client/policy/BatchDeletePolicy.java b/client/src/com/aerospike/client/policy/BatchDeletePolicy.java
index 3953190dc..151d0f9df 100644
--- a/client/src/com/aerospike/client/policy/BatchDeletePolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchDeletePolicy.java
@@ -24,7 +24,23 @@
 import com.aerospike.client.exp.Expression;
 
 /**
- * Policy attributes used in batch delete commands.
+ * Policy for batch delete: optional filter expression and commit level.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#delete(BatchPolicy, BatchDeletePolicy, Key[])}. Omit or use null for defaults.
+ *
+ * <p><b>Example:</b>
+ * <p>Use master-only commit for batch delete to reduce latency.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchDeletePolicy bdp = new BatchDeletePolicy();
+ * bdp.commitLevel = CommitLevel.COMMIT_MASTER;
+ * client.delete(batchPolicy, bdp, keys);
+ * }</pre>
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#delete
+ * @see CommitLevel
  */
 public final class BatchDeletePolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/BatchPolicy.java b/client/src/com/aerospike/client/policy/BatchPolicy.java
index 1b8b32cc5..2291bfd19 100644
--- a/client/src/com/aerospike/client/policy/BatchPolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchPolicy.java
@@ -26,7 +26,25 @@
 import java.util.Objects;
 
 /**
- * Batch parent policy.
+ * Policy for batch get, batch write, batch delete, and batch operate: concurrency, inline processing, and respond-all-keys.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#get}, {@link com.aerospike.client.AerospikeClient#operate}, {@link com.aerospike.client.AerospikeClient#delete} batch overloads. Extends {@link Policy}.
+ *
+ * <p><b>Example:</b>
+ * <p>Allow inline batch processing and set a 2-second total timeout for batch get.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy policy = new BatchPolicy();
+ * policy.allowInline = true;
+ * policy.totalTimeout = 2000;
+ * Record[] records = client.get(policy, keys);
+ * }</pre>
+ *
+ * @see Policy
+ * @see BatchWritePolicy
+ * @see BatchDeletePolicy
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see com.aerospike.client.AerospikeClient#operate
  */
 public class BatchPolicy extends Policy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/BatchReadPolicy.java b/client/src/com/aerospike/client/policy/BatchReadPolicy.java
index 88cd54e3d..b5469e02d 100644
--- a/client/src/com/aerospike/client/policy/BatchReadPolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchReadPolicy.java
@@ -19,7 +19,24 @@
 import com.aerospike.client.exp.Expression;
 
 /**
- * Policy attributes used in batch read commands.
+ * Policy for batch read: optional filter expression, read mode (AP/SC), replica, and read-touch-TTL.
+ * <p>
+ * Pass to batch get overloads when using key-specific policies; otherwise batch uses {@link BatchPolicy} and default read behavior.
+ *
+ * <p><b>Example:</b>
+ * <p>Use availability read mode ONE for batch reads when passing key-specific policies (e.g. in BatchRecord).</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchReadPolicy brp = new BatchReadPolicy();
+ * brp.readModeAP = ReadModeAP.ONE;
+ * Record[] records = client.get(batchPolicy, keys);
+ * }</pre>
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#get
+ * @see ReadModeAP
+ * @see ReadModeSC
  */
 public final class BatchReadPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/BatchUDFPolicy.java b/client/src/com/aerospike/client/policy/BatchUDFPolicy.java
index 525468837..a9f2ce0a5 100644
--- a/client/src/com/aerospike/client/policy/BatchUDFPolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchUDFPolicy.java
@@ -24,7 +24,23 @@
 import com.aerospike.client.exp.Expression;
 
 /**
- * Policy attributes used in batch UDF execute commands.
+ * Policy for batch UDF execute: optional filter expression and commit level.
+ * <p>
+ * Pass to batch execute overloads. Omit or use null for defaults.
+ *
+ * <p><b>Example:</b>
+ * <p>Run batch UDF execute with commit-all consistency so all replicas commit before returning.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchUDFPolicy budfp = new BatchUDFPolicy();
+ * budfp.commitLevel = CommitLevel.COMMIT_ALL;
+ * client.execute(batchPolicy, budfp, keys, "pkg", "func", Value.get("arg"));
+ * }</pre>
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#execute
+ * @see CommitLevel
  */
 public final class BatchUDFPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/BatchWritePolicy.java b/client/src/com/aerospike/client/policy/BatchWritePolicy.java
index d33c0b9d4..2dd22760c 100644
--- a/client/src/com/aerospike/client/policy/BatchWritePolicy.java
+++ b/client/src/com/aerospike/client/policy/BatchWritePolicy.java
@@ -24,7 +24,24 @@
 import com.aerospike.client.exp.Expression;
 
 /**
- * Policy attributes used in batch write commands.
+ * Policy for batch write and batch operate write operations: filter expression, record-exists action, generation, commit level, expiration.
+ * <p>
+ * Pass to batch operate or batch write overloads alongside {@link BatchPolicy}. Extends write options per key when using key-specific policies.
+ *
+ * <p><b>Example:</b>
+ * <p>Replace existing records and commit to master only for batch operate or batch write.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * BatchPolicy batchPolicy = new BatchPolicy();
+ * BatchWritePolicy bwp = new BatchWritePolicy();
+ * bwp.recordExistsAction = RecordExistsAction.REPLACE;
+ * bwp.commitLevel = CommitLevel.COMMIT_MASTER;
+ * client.operate(batchPolicy, batchRecordList);
+ * }</pre>
+ *
+ * @see BatchPolicy
+ * @see com.aerospike.client.AerospikeClient#operate
+ * @see Policy#filterExp
  */
 public final class BatchWritePolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/ClientPolicy.java b/client/src/com/aerospike/client/policy/ClientPolicy.java
index e2a5027c6..2b386e590 100644
--- a/client/src/com/aerospike/client/policy/ClientPolicy.java
+++ b/client/src/com/aerospike/client/policy/ClientPolicy.java
@@ -33,7 +33,34 @@
 import com.aerospike.client.util.Util;
 
 /**
- * Container object for client policy Command.
+ * Client-level configuration: connection limits, timeouts, auth, default policies, and optional event loops for async.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient} constructors. Default policies (read, write, batch, etc.) are used when null is passed to operations.
+ *
+ * <p><b>Example:</b>
+ * <p>Connect to the cluster with authentication and a 2-second tend timeout.</p>
+ * <pre>{@code
+ * ClientPolicy policy = new ClientPolicy();
+ * policy.user = "admin";
+ * policy.password = "secret";
+ * policy.timeout = 2000;
+ * IAerospikeClient client = new AerospikeClient(policy, "localhost", 3000);
+ * client.close();
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient
+ * @see Policy
+ * @see WritePolicy
+ * @see QueryPolicy
+ * @see ScanPolicy
+ * @see BatchPolicy
+ * @see BatchWritePolicy
+ * @see BatchDeletePolicy
+ * @see BatchUDFPolicy
+ * @see TxnVerifyPolicy
+ * @see TxnRollPolicy
+ * @see InfoPolicy
+ * @see TlsPolicy
  */
 public class ClientPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/CommitLevel.java b/client/src/com/aerospike/client/policy/CommitLevel.java
index 72ffdc391..75e11adc2 100644
--- a/client/src/com/aerospike/client/policy/CommitLevel.java
+++ b/client/src/com/aerospike/client/policy/CommitLevel.java
@@ -17,7 +17,11 @@
 package com.aerospike.client.policy;
 
 /**
- * Desired consistency guarantee when committing a command on the server.
+ * Consistency guarantee when committing a write on the server (all replicas vs master only).
+ *
+ * @see WritePolicy#commitLevel
+ * @see BatchDeletePolicy#commitLevel
+ * @see BatchUDFPolicy#commitLevel
  */
 public enum CommitLevel {
 	/**
diff --git a/client/src/com/aerospike/client/policy/GenerationPolicy.java b/client/src/com/aerospike/client/policy/GenerationPolicy.java
index c1ddf89a3..cd1633165 100644
--- a/client/src/com/aerospike/client/policy/GenerationPolicy.java
+++ b/client/src/com/aerospike/client/policy/GenerationPolicy.java
@@ -17,7 +17,9 @@
 package com.aerospike.client.policy;
 
 /**
- * How to handle record writes based on record generation.
+ * How to handle record writes based on record generation (optimistic concurrency).
+ *
+ * @see WritePolicy#generationPolicy
  */
 public enum GenerationPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/InfoPolicy.java b/client/src/com/aerospike/client/policy/InfoPolicy.java
index 88dd409f3..8b3a56038 100644
--- a/client/src/com/aerospike/client/policy/InfoPolicy.java
+++ b/client/src/com/aerospike/client/policy/InfoPolicy.java
@@ -17,7 +17,20 @@
 package com.aerospike.client.policy;
 
 /**
- * Policy attributes used for info commands.
+ * Policy for info protocol requests to a node; currently supports socket timeout.
+ * <p>
+ * Pass to {@link com.aerospike.client.Info#request} and related overloads, or use for cluster tend. Default timeout is 1000 ms.
+ *
+ * <p><b>Example:</b>
+ * <p>Use a 2-second socket timeout for info requests to a node (e.g. to fetch "build").</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * InfoPolicy policy = new InfoPolicy();
+ * policy.timeout = 2000;
+ * String build = Info.request(policy, client.getNodes()[0], "build");
+ * }</pre>
+ *
+ * @see com.aerospike.client.Info#request
  */
 public final class InfoPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/Policy.java b/client/src/com/aerospike/client/policy/Policy.java
index d8be235d2..1367bc792 100644
--- a/client/src/com/aerospike/client/policy/Policy.java
+++ b/client/src/com/aerospike/client/policy/Policy.java
@@ -27,7 +27,24 @@
 import com.aerospike.client.exp.Expression;
 
 /**
- * Command policy attributes used in all database commands.
+ * Base policy for all database commands: timeouts, retries, replica selection, optional expression filter and transaction.
+ * <p>
+ * Subclasses define operation-specific options (e.g. {@link WritePolicy}, {@link QueryPolicy}). Set {@link #txn} for multi-record transactions.
+ *
+ * <p><b>Example (expression filter):</b>
+ * <p>Apply an expression filter so only records where bin "a" equals 11 are read.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Policy p = new Policy();
+ * p.filterExp = Exp.build(Exp.eq(Exp.intBin("a"), Exp.val(11)));
+ * client.get(p, key);
+ * }</pre>
+ *
+ * @see WritePolicy
+ * @see QueryPolicy
+ * @see ScanPolicy
+ * @see BatchPolicy
+ * @see com.aerospike.client.Txn
  */
 public class Policy {
 	/**
@@ -65,11 +82,7 @@ public class Policy {
 	 * command is ignored.
 	 * <p>
 	 * Default: null
-	 * <p>
-	 * <pre>Example:{@code
-	 * Policy p = new Policy();
-	 * p.filterExp = Exp.build(Exp.eq(Exp.intBin("a"), Exp.val(11)));
-	 * }</pre>
+	 * See class-level example for {@link com.aerospike.client.exp.Exp#build} usage.
 	 */
 	public Expression filterExp;
 
diff --git a/client/src/com/aerospike/client/policy/QueryDuration.java b/client/src/com/aerospike/client/policy/QueryDuration.java
index 9c41ac218..2233a18f3 100644
--- a/client/src/com/aerospike/client/policy/QueryDuration.java
+++ b/client/src/com/aerospike/client/policy/QueryDuration.java
@@ -17,8 +17,9 @@
 package com.aerospike.client.policy;
 
 /**
- * Expected query duration. The server treats the query in different ways depending on the expected duration.
- * This enum is ignored for aggregation queries, background queries and server versions &lt; 6.0.
+ * Expected query duration (LONG or SHORT); server optimizes accordingly. Ignored for aggregation, background queries, and server versions before 6.0.
+ *
+ * @see QueryPolicy#expectedDuration
  */
 public enum QueryDuration {
 	/**
diff --git a/client/src/com/aerospike/client/policy/QueryPolicy.java b/client/src/com/aerospike/client/policy/QueryPolicy.java
index 1bacb8e57..ad4798d58 100644
--- a/client/src/com/aerospike/client/policy/QueryPolicy.java
+++ b/client/src/com/aerospike/client/policy/QueryPolicy.java
@@ -23,10 +23,24 @@
 import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicQueryConfig;
 
 /**
- * Container object for policy attributes used in query operations.
+ * Policy for query and scan operations: expected duration, max records, concurrency, record queue size, and include-bin-data.
  * <p>
- * Inherited Policy fields {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored
- * in query commands.
+ * Pass to {@link com.aerospike.client.AerospikeClient#query} and {@link com.aerospike.client.AerospikeClient#queryAggregate}. {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored for query.
+ *
+ * <p><b>Example:</b>
+ * <p>Run a short-duration query and include bin data in the returned records.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * QueryPolicy policy = new QueryPolicy();
+ * policy.expectedDuration = QueryDuration.SHORT;
+ * policy.includeBinData = true;
+ * RecordSet rs = client.query(policy, stmt);
+ * rs.close();
+ * }</pre>
+ *
+ * @see Policy
+ * @see com.aerospike.client.query.Statement
+ * @see com.aerospike.client.AerospikeClient#query
  */
 public class QueryPolicy extends Policy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/ReadModeAP.java b/client/src/com/aerospike/client/policy/ReadModeAP.java
index ac4edbdaa..a9bce7375 100644
--- a/client/src/com/aerospike/client/policy/ReadModeAP.java
+++ b/client/src/com/aerospike/client/policy/ReadModeAP.java
@@ -17,10 +17,10 @@
 package com.aerospike.client.policy;
 
 /**
- * Read policy for AP (availability) namespaces.
- * <p>
- * How duplicates should be consulted in a read operation.
- * Only makes a difference during migrations and only applicable in AP mode.
+ * Read policy for AP (availability) namespaces; how many duplicates to consult (ONE or ALL). Only applies during migrations in AP mode.
+ *
+ * @see Policy#readModeAP
+ * @see BatchReadPolicy#readModeAP
  */
 public enum ReadModeAP {
 	/**
diff --git a/client/src/com/aerospike/client/policy/ReadModeSC.java b/client/src/com/aerospike/client/policy/ReadModeSC.java
index eed429b13..d07df2788 100644
--- a/client/src/com/aerospike/client/policy/ReadModeSC.java
+++ b/client/src/com/aerospike/client/policy/ReadModeSC.java
@@ -17,9 +17,10 @@
 package com.aerospike.client.policy;
 
 /**
- * Read policy for SC (strong consistency) namespaces.
- * <p>
- * Determines SC read consistency options.
+ * Read policy for SC (strong consistency) namespaces; session, linearize, or allow-unavailable.
+ *
+ * @see Policy#readModeSC
+ * @see BatchReadPolicy#readModeSC
  */
 public enum ReadModeSC {
 	/**
diff --git a/client/src/com/aerospike/client/policy/RecordExistsAction.java b/client/src/com/aerospike/client/policy/RecordExistsAction.java
index 818488fd8..67f8380a3 100644
--- a/client/src/com/aerospike/client/policy/RecordExistsAction.java
+++ b/client/src/com/aerospike/client/policy/RecordExistsAction.java
@@ -17,7 +17,10 @@
 package com.aerospike.client.policy;
 
 /**
- * How to handle writes when the record already exists.
+ * How to handle writes when the record already exists (update, replace, create-only, etc.).
+ *
+ * @see WritePolicy#recordExistsAction
+ * @see BatchWritePolicy#recordExistsAction
  */
 public enum RecordExistsAction {
 	/**
diff --git a/client/src/com/aerospike/client/policy/Replica.java b/client/src/com/aerospike/client/policy/Replica.java
index 655f18b9d..d1335a715 100644
--- a/client/src/com/aerospike/client/policy/Replica.java
+++ b/client/src/com/aerospike/client/policy/Replica.java
@@ -17,7 +17,9 @@
 package com.aerospike.client.policy;
 
 /**
- * Defines algorithm used to determine the target node for a command.
+ * Algorithm used to determine the target node for a partition (master, replica, rack-aware, etc.).
+ *
+ * @see Policy#replica
  */
 public enum Replica {
 	/**
diff --git a/client/src/com/aerospike/client/policy/ScanPolicy.java b/client/src/com/aerospike/client/policy/ScanPolicy.java
index 0ff0eec7f..4a27015f0 100644
--- a/client/src/com/aerospike/client/policy/ScanPolicy.java
+++ b/client/src/com/aerospike/client/policy/ScanPolicy.java
@@ -23,15 +23,24 @@
 import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicScanConfig;
 
 /**
- * Container object for optional parameters used in scan operations.
+ * Policy for scan operations (max records, records per second, concurrent nodes, include bin data).
  * <p>
- * Inherited Policy fields {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored in
- * scan commands.
+ * {@link Policy#txn} and {@link Policy#failOnFilteredOut} are ignored for scan.
  *
- * @deprecated Scan operation related policies have been deprecated and will be removed eventually.
- * <p>Use {@link QueryPolicy} with {@link com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.QueryListener)}
- * or {@link com.aerospike.client.AerospikeClient#queryPartitions(com.aerospike.client.policy.QueryPolicy, com.aerospike.client.query.Statement, com.aerospike.client.query.PartitionFilter)}
- * instead (use statement with namespace and set name, no filter).</p>
+ * <p><b>Example:</b>
+ * <p>Run a scan with a record limit and include bin data (prefer {@link QueryPolicy} with query for new code).</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * ScanPolicy policy = new ScanPolicy();
+ * policy.maxRecords = 1000;
+ * policy.includeBinData = true;
+ * client.scanAll(policy, "test", "set1", (key, record) -> { }, "mybin");
+ * }</pre>
+ *
+ * @deprecated Use {@link QueryPolicy} with {@link com.aerospike.client.AerospikeClient#query} or {@link com.aerospike.client.AerospikeClient#queryPartitions} and a {@link com.aerospike.client.query.Statement} with namespace and set name (no filter).
+ *
+ * @see QueryPolicy
+ * @see com.aerospike.client.AerospikeClient#query
  */
 @Deprecated
 public final class ScanPolicy extends Policy {
diff --git a/client/src/com/aerospike/client/policy/TCPKeepAlive.java b/client/src/com/aerospike/client/policy/TCPKeepAlive.java
index c282d58f8..7f0f8d56b 100644
--- a/client/src/com/aerospike/client/policy/TCPKeepAlive.java
+++ b/client/src/com/aerospike/client/policy/TCPKeepAlive.java
@@ -18,6 +18,16 @@
 
 /**
  * TCP keep-alive policy. This configuration only referenced when using native Netty epoll library.
+ * <p><b>Example:</b>
+ * <p>Enable TCP keep-alive with custom idle/interval/probes when using Netty epoll (set on {@link ClientPolicy#keepAlive}).</p>
+ * <pre>{@code
+ * TCPKeepAlive keepAlive = new TCPKeepAlive(60, 10, 3);
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.keepAlive = keepAlive;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 3000);
+ * }</pre>
+ *
+ * @see ClientPolicy#keepAlive
  */
 public final class TCPKeepAlive {
 	/**
diff --git a/client/src/com/aerospike/client/policy/TlsPolicy.java b/client/src/com/aerospike/client/policy/TlsPolicy.java
index ff4448d1d..8162b16e7 100644
--- a/client/src/com/aerospike/client/policy/TlsPolicy.java
+++ b/client/src/com/aerospike/client/policy/TlsPolicy.java
@@ -23,8 +23,23 @@
 import com.aerospike.client.async.NettyTlsContext;
 
 /**
- * TLS connection policy.  Secure TLS connections are supported for
- * synchronous commands and netty backed asynchronous commands.
+ * TLS connection policy for secure connections; supported for sync and Netty-backed async commands.
+ * <p>
+ * Set on {@link ClientPolicy#tlsPolicy}. Optionally provide {@link #context} (SSLContext) or {@link #nettyContext} (NettyTlsContext) for shared TLS state across clients.
+ *
+ * <p><b>Example:</b>
+ * <p>Connect over TLS using TLSv1.2 by attaching TlsPolicy to ClientPolicy.</p>
+ * <pre>{@code
+ * TlsPolicy tp = new TlsPolicy();
+ * tp.protocols = new String[] {"TLSv1.2"};
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.tlsPolicy = tp;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 4333);
+ * client.close();
+ * }</pre>
+ *
+ * @see ClientPolicy#tlsPolicy
+ * @see com.aerospike.client.AerospikeClient
  */
 public final class TlsPolicy {
 	/**
@@ -49,8 +64,8 @@ public final class TlsPolicy {
 	 * ClientPolicy cp = new ClientPolicy();
 	 * cp.tlsPolicy = tp;
 	 *
-	 * AerospikeClient cluster1 = new AerospikeClient(cp, "host1", 3000);
-	 * AerospikeClient cluster2 = new AerospikeClient(cp, "host2", 3000);
+	 * IAerospikeClient cluster1 = new AerospikeClient(cp, "host1", 3000);
+	 * IAerospikeClient cluster2 = new AerospikeClient(cp, "host2", 3000);
 	 * }</pre>
 	 *
 	 * Default: null (create NettyTlsContext for each AerospikeClient instance when netty is used).
diff --git a/client/src/com/aerospike/client/policy/TxnRollPolicy.java b/client/src/com/aerospike/client/policy/TxnRollPolicy.java
index 9601e3d83..592e27944 100644
--- a/client/src/com/aerospike/client/policy/TxnRollPolicy.java
+++ b/client/src/com/aerospike/client/policy/TxnRollPolicy.java
@@ -23,8 +23,24 @@
 import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicTxnRollConfig;
 
 /**
- * Transaction policy fields used to batch roll forward/backward records on
- * commit or abort. Used a placeholder for now as there are no additional fields beyond BatchPolicy.
+ * Policy for transaction roll forward/backward phase on commit or abort; extends {@link BatchPolicy} with no extra fields.
+ * <p>
+ * Used internally when {@link com.aerospike.client.AerospikeClient#commit} or {@link com.aerospike.client.AerospikeClient#abort} applies write results. Can be set on {@link ClientPolicy#txnRollPolicyDefault}.
+ *
+ * <p><b>Example:</b>
+ * <p>Set a custom transaction roll policy as the client default for commit/abort phase.</p>
+ * <pre>{@code
+ * TxnRollPolicy trp = new TxnRollPolicy();
+ * trp.totalTimeout = 15000;
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.txnRollPolicyDefault = trp;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 3000);
+ * }</pre>
+ *
+ * @see BatchPolicy
+ * @see ClientPolicy#txnRollPolicyDefault
+ * @see com.aerospike.client.AerospikeClient#commit
+ * @see com.aerospike.client.AerospikeClient#abort
  */
 public class TxnRollPolicy extends BatchPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java b/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java
index cafda0fdd..4915d7f53 100644
--- a/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java
+++ b/client/src/com/aerospike/client/policy/TxnVerifyPolicy.java
@@ -23,8 +23,23 @@
 import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicTxnVerifyConfig;
 
 /**
- * Transaction policy fields used to batch verify record versions on commit.
- * Used a placeholder for now as there are no additional fields beyond BatchPolicy.
+ * Policy for transaction verify phase (batch read of record versions before commit); extends {@link BatchPolicy} with no extra fields.
+ * <p>
+ * Used internally when {@link com.aerospike.client.AerospikeClient#commit} verifies read keys. Can be set on {@link ClientPolicy#txnVerifyPolicyDefault}.
+ *
+ * <p><b>Example:</b>
+ * <p>Set a custom transaction verify policy as the client default for the commit verify phase.</p>
+ * <pre>{@code
+ * TxnVerifyPolicy tvp = new TxnVerifyPolicy();
+ * tvp.socketTimeout = 5000;
+ * ClientPolicy cp = new ClientPolicy();
+ * cp.txnVerifyPolicyDefault = tvp;
+ * IAerospikeClient client = new AerospikeClient(cp, "localhost", 3000);
+ * }</pre>
+ *
+ * @see BatchPolicy
+ * @see ClientPolicy#txnVerifyPolicyDefault
+ * @see com.aerospike.client.AerospikeClient#commit
  */
 public class TxnVerifyPolicy extends BatchPolicy {
 	/**
diff --git a/client/src/com/aerospike/client/policy/WritePolicy.java b/client/src/com/aerospike/client/policy/WritePolicy.java
index cbc1d460d..8a9bb880a 100644
--- a/client/src/com/aerospike/client/policy/WritePolicy.java
+++ b/client/src/com/aerospike/client/policy/WritePolicy.java
@@ -25,8 +25,25 @@
 import com.aerospike.client.configuration.serializers.dynamicconfig.DynamicWriteConfig;
 
 /**
- * Container object for policy attributes used in write operations.
- * This object is passed into methods where database writes can occur.
+ * Policy for write operations: record-exists action, generation policy, commit level, expiration, and related options.
+ * <p>
+ * Pass to put, append, prepend, add, delete, touch, operate, and execute. Extends {@link Policy} for timeouts and retries.
+ *
+ * <p><b>Example:</b>
+ * <p>Replace existing records and set record TTL to one hour (3600 seconds).</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * WritePolicy wp = new WritePolicy();
+ * wp.recordExistsAction = RecordExistsAction.REPLACE;
+ * wp.expiration = 3600;
+ * client.put(wp, key, new Bin("name", "Alice"));
+ * }</pre>
+ *
+ * @see Policy
+ * @see RecordExistsAction
+ * @see GenerationPolicy
+ * @see com.aerospike.client.AerospikeClient#put
+ * @see com.aerospike.client.AerospikeClient#operate
  */
 public final class WritePolicy extends Policy {
 	/**
diff --git a/client/src/com/aerospike/client/query/Filter.java b/client/src/com/aerospike/client/query/Filter.java
index 77e7da056..f5fe0944f 100644
--- a/client/src/com/aerospike/client/query/Filter.java
+++ b/client/src/com/aerospike/client/query/Filter.java
@@ -26,9 +26,28 @@
 import com.aerospike.client.util.Pack;
 
 /**
- * Query filter definition.
+ * Query filter definition; exactly one filter per {@link Statement}, on a bin that has a secondary index.
+ * <p>
+ * Use {@link #equal(String, long, CTX...)}, {@link #equal(String, String, CTX...)}, {@link #range}, or other static methods; pass to {@link Statement#setFilter}. Use optional {@link com.aerospike.client.cdt.CTX} for CDT/list/map context (e.g. {@link #range(String, long, long, CTX...)}).
+ * <p>Set Filter.equal on a statement and run query.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("users");
+ * stmt.setFilter(Filter.equal("status", "active"));
+ * RecordSet rs = client.query(null, stmt);
+ * try {
+ *   while (rs.next()) { KeyRecord kr = rs.getKeyRecord(); }
+ * } finally { rs.close(); }
+ * client.close();
+ * }</pre>
  *
- * Currently, only one filter is allowed in a Statement, and must be on bin which has a secondary index defined.
+ * @see Statement
+ * @see Statement#setFilter
+ * @see IndexType
+ * @see IndexCollectionType
+ * @see com.aerospike.client.cdt.CTX
  */
 public final class Filter {
 	/**
diff --git a/client/src/com/aerospike/client/query/IndexCollectionType.java b/client/src/com/aerospike/client/query/IndexCollectionType.java
index c5fee4fbc..0521f9dac 100644
--- a/client/src/com/aerospike/client/query/IndexCollectionType.java
+++ b/client/src/com/aerospike/client/query/IndexCollectionType.java
@@ -17,7 +17,13 @@
 package com.aerospike.client.query;
 
 /**
- * Secondary index collection type.
+ * Whether the secondary index is on a scalar bin, list elements, or map keys/values; used with {@link IndexType} when creating an index and in {@link Filter}.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#createIndex} for list/map bins; use the same value in {@link Filter#range} or {@link Filter#equal} for CDT context.
+ *
+ * @see IndexType
+ * @see Filter
+ * @see com.aerospike.client.AerospikeClient#createIndex
  */
 public enum IndexCollectionType {
 	/**
diff --git a/client/src/com/aerospike/client/query/IndexType.java b/client/src/com/aerospike/client/query/IndexType.java
index 5cfb445c4..f28e74059 100644
--- a/client/src/com/aerospike/client/query/IndexType.java
+++ b/client/src/com/aerospike/client/query/IndexType.java
@@ -17,7 +17,13 @@
 package com.aerospike.client.query;
 
 /**
- * Underlying data type of secondary index.
+ * Data type of a secondary index; used when creating an index and must match the bin type and {@link Filter}.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#createIndex} and {@link com.aerospike.client.AerospikeClient#dropIndex}. Use with {@link IndexCollectionType} for list/map indexes.
+ *
+ * @see IndexCollectionType
+ * @see Filter
+ * @see com.aerospike.client.AerospikeClient#createIndex
  */
 public enum IndexType {
 	/**
diff --git a/client/src/com/aerospike/client/query/KeyRecord.java b/client/src/com/aerospike/client/query/KeyRecord.java
index e1d401b37..d856a924e 100644
--- a/client/src/com/aerospike/client/query/KeyRecord.java
+++ b/client/src/com/aerospike/client/query/KeyRecord.java
@@ -22,7 +22,25 @@
 import java.util.Objects;
 
 /**
- * Container object for key identifier and record data.
+ * Key and record pair returned by query/scan iteration; obtained from {@link RecordSet#getKeyRecord()} after {@link RecordSet#next()}.
+ * <p>
+ * In normal iteration {@link #key} is not null; {@link #record} is null when the key was not found. Also used as sentinel {@link RecordSet#END}.
+ * <p>Iterate query results and get KeyRecord from RecordSet.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * RecordSet rs = client.query(null, stmt);
+ * try {
+ *   while (rs.next()) {
+ *     KeyRecord kr = rs.getKeyRecord();
+ *     if (kr.record != null) { Object v = kr.record.getValue("mybin"); }
+ *   }
+ * } finally { rs.close(); }
+ * client.close();
+ * }</pre>
+ *
+ * @see RecordSet
+ * @see com.aerospike.client.Key
+ * @see com.aerospike.client.Record
  */
 public final class KeyRecord {
 	/**
diff --git a/client/src/com/aerospike/client/query/PartitionFilter.java b/client/src/com/aerospike/client/query/PartitionFilter.java
index e37e393a7..8f760a8b1 100644
--- a/client/src/com/aerospike/client/query/PartitionFilter.java
+++ b/client/src/com/aerospike/client/query/PartitionFilter.java
@@ -29,6 +29,22 @@
  * after the last record read (in digest order) in each partition in the previous scan/query.
  * To reset the cursor of an existing PartitionFilter instance, call
  * {@link #setPartitions(PartitionStatus[])} with a null argument.
+ * <p>Query a partition range with queryPartitions.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * PartitionFilter filter = PartitionFilter.range(0, 100);
+ * RecordSet rs = client.queryPartitions(null, stmt, filter);
+ * try {
+ *   while (rs.next()) { KeyRecord kr = rs.getKeyRecord(); }
+ * } finally { rs.close(); }
+ * client.close();
+ * }</pre>
+ *
+ * @see com.aerospike.client.AerospikeClient#queryPartitions
+ * @see Statement
  */
 public final class PartitionFilter implements Serializable {
 	private static final long serialVersionUID = 4L;
diff --git a/client/src/com/aerospike/client/query/QueryListener.java b/client/src/com/aerospike/client/query/QueryListener.java
index b8db35b72..9da4c88ad 100644
--- a/client/src/com/aerospike/client/query/QueryListener.java
+++ b/client/src/com/aerospike/client/query/QueryListener.java
@@ -21,22 +21,34 @@
 import com.aerospike.client.Record;
 
 /**
- * Result notification for sync query command.
- * The results are sent one record at a time.
+ * Callback for each record in a synchronous secondary-index query; results are streamed one record at a time.
+ * <p>
+ * Pass to {@link com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, Statement, QueryListener)} when processing records one-by-one instead of buffering a {@link RecordSet}. Throw {@link com.aerospike.client.AerospikeException.QueryTerminated} from {@link #onRecord} to abort.
+ * <p>Query with a QueryListener to process each record in a callback.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * stmt.setFilter(Filter.equal("status", "active"));
+ * client.query(null, stmt, (key, record) -> {
+ *   if (record != null) { Object val = record.getValue("mybin"); }
+ * });
+ * client.close();
+ * }</pre>
+ *
+ * @see RecordSet
+ * @see Statement
+ * @see Filter
+ * @see com.aerospike.client.AerospikeClient#query(com.aerospike.client.policy.QueryPolicy, Statement, QueryListener)
+ * @see com.aerospike.client.AerospikeException.QueryTerminated
  */
 public interface QueryListener {
 	/**
-	 * This method is called when a record is received from the server.
-	 * The receive sequence is not ordered.
-	 * <p>
-	 * The user may throw a
-	 * {@link com.aerospike.client.AerospikeException.QueryTerminated AerospikeException.QueryTerminated}
-	 * exception if the command should be aborted. If an exception is thrown, parallel query command
-	 * threads to other nodes will also be terminated.
-	 *
-	 * @param key					unique record identifier
-	 * @param record				record instance
-	 * @throws AerospikeException	if error occurs or query should be terminated.
+	 * Called when a record is received; order is not guaranteed. Throw {@link com.aerospike.client.AerospikeException.QueryTerminated} to abort.
+	 * @param key record key (must not be null)
+	 * @param record record if found, otherwise null
+	 * @throws AerospikeException when the query should be terminated (e.g. throw QueryTerminated to abort)
 	 */
 	public void onRecord(Key key, Record record);
 }
diff --git a/client/src/com/aerospike/client/query/RecordSet.java b/client/src/com/aerospike/client/query/RecordSet.java
index 11cc6a568..082aaf72d 100644
--- a/client/src/com/aerospike/client/query/RecordSet.java
+++ b/client/src/com/aerospike/client/query/RecordSet.java
@@ -26,11 +26,36 @@
 import com.aerospike.client.Record;
 
 /**
- * This class manages record retrieval from queries.
- * Multiple threads will retrieve records from the server nodes and put these records on the queue.
- * The single user thread consumes these records from the queue.
+ * Iterable set of key/record pairs from a query; call {@link #next()} then {@link #getKeyRecord()} (or iterate) and always {@link #close()} when done.
+ * <p>
+ * Returned by {@link com.aerospike.client.AerospikeClient#query}. Use {@link #END} to detect end when iterating; {@link #next()} returns false when no more records. Close in a finally block to release resources.
+ * <p>Run a query and iterate RecordSet with next() and getKeyRecord().</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * stmt.setFilter(Filter.equal("bin1", 1));
+ * RecordSet rs = client.query(null, stmt);
+ * try {
+ *   while (rs.next()) {
+ *     KeyRecord kr = rs.getKeyRecord();
+ *     if (kr.record != null) { Object v = kr.record.getValue("mybin"); }
+ *   }
+ * } finally {
+ *   rs.close();
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see KeyRecord
+ * @see ResultSet
+ * @see QueryListener
+ * @see Statement
+ * @see com.aerospike.client.AerospikeClient#query
  */
 public class RecordSet implements Iterable<KeyRecord>, Closeable {
+	/** Sentinel indicating no more records; do not use as application data. */
 	public static final KeyRecord END = new KeyRecord(null, null);
 
 	private final IQueryExecutor executor;
@@ -59,10 +84,9 @@ protected RecordSet() {
 	//-------------------------------------------------------
 
 	/**
-	 * Retrieve next record.  This method will block until a record is retrieved
-	 * or the query is cancelled.
-	 *
-	 * @return whether record exists - if false, no more records are available
+	 * Advances to the next record; blocks until a record is available or the query ends.
+	 * @return true if a record is available (use {@link #getKeyRecord()}); false when no more records
+	 * @throws AerospikeException when the query fails on the server (e.g. timeout, connection error, or invalid statement)
 	 */
 	public boolean next() throws AerospikeException {
 		if (! valid) {
@@ -92,9 +116,7 @@ record = queue.take();
 		return true;
 	}
 
-	/**
-	 * Close query.
-	 */
+	/** Closes this record set and releases resources; call in a finally block. */
 	public void close() {
 		valid = false;
 
diff --git a/client/src/com/aerospike/client/query/RegexFlag.java b/client/src/com/aerospike/client/query/RegexFlag.java
index 0c5e4c714..a0fb4a92c 100644
--- a/client/src/com/aerospike/client/query/RegexFlag.java
+++ b/client/src/com/aerospike/client/query/RegexFlag.java
@@ -17,11 +17,16 @@
 package com.aerospike.client.query;
 
 /**
- * Regex bit flags. Use BITWISE OR to combine flags. Example:
- * 
- * <pre>{@code 
+ * Regex bit flags for expression and filter regex; combine with BITWISE OR.
+ * <p>
+ * Used in {@link com.aerospike.client.exp.Exp#regexCompare} and filter APIs that accept regex flags.
+ * <p>Combine regex flags with bitwise OR.</p>
+ * <pre>{@code
  * int flags = RegexFlag.ICASE | RegexFlag.NEWLINE;
  * }</pre>
+ *
+ * @see com.aerospike.client.exp.Exp#regexCompare
+ * @see Filter
  */
 public final class RegexFlag {
 	/**
diff --git a/client/src/com/aerospike/client/query/ResultSet.java b/client/src/com/aerospike/client/query/ResultSet.java
index b8d1b5ace..ac8239211 100644
--- a/client/src/com/aerospike/client/query/ResultSet.java
+++ b/client/src/com/aerospike/client/query/ResultSet.java
@@ -25,11 +25,33 @@
 import com.aerospike.client.Log;
 
 /**
- * This class manages result retrieval from queries.
- * Multiple threads will retrieve results from the server nodes and put these results on the queue.
- * The single user thread consumes these results from the queue.
+ * Iterable set of aggregation UDF results; call {@link #next()} then {@link #getObject()} (or iterate) and always {@link #close()} when done.
+ * <p>
+ * Returned by {@link com.aerospike.client.AerospikeClient#queryAggregate}. Use {@link #END} to detect end when iterating; {@link #next()} returns false when no more results. Close in a finally block to release resources.
+ * <p>Run queryAggregate and iterate ResultSet with next() and getObject().</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * stmt.setFilter(Filter.equal("bin1", 1));
+ * ResultSet rs = client.queryAggregate(null, stmt);
+ * try {
+ *   while (rs.next()) {
+ *     Object obj = rs.getObject();
+ *   }
+ * } finally {
+ *   rs.close();
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see RecordSet
+ * @see Statement
+ * @see com.aerospike.client.AerospikeClient#queryAggregate
  */
 public class ResultSet implements Iterable<Object>, Closeable {
+	/** Sentinel indicating no more results; do not use as application data. */
 	public static final Object END = new Object();
 
 	private final QueryAggregateExecutor executor;
@@ -58,10 +80,9 @@ protected ResultSet() {
 	//-------------------------------------------------------
 
 	/**
-	 * Retrieve next result.  This method will block until a result is retrieved
-	 * or the query is cancelled.
-	 *
-	 * @return whether result exists - if false, no more results are available
+	 * Advances to the next result; blocks until a result is available or the query ends.
+	 * @return true if a result is available (use {@link #getObject()}); false when no more results
+	 * @throws AerospikeException when the query fails on the server (e.g. timeout, connection error, or invalid statement)
 	 */
 	public boolean next() throws AerospikeException {
 		if (!valid) {
diff --git a/client/src/com/aerospike/client/query/Statement.java b/client/src/com/aerospike/client/query/Statement.java
index 290815517..026158d72 100644
--- a/client/src/com/aerospike/client/query/Statement.java
+++ b/client/src/com/aerospike/client/query/Statement.java
@@ -21,7 +21,35 @@
 import com.aerospike.client.util.RandomShift;
 
 /**
- * Query statement parameters.
+ * Parameters for a secondary-index query or scan: namespace, set, optional {@link Filter}, bin names, and optional aggregation.
+ * <p>
+ * Use with {@link com.aerospike.client.AerospikeClient#query}, {@link com.aerospike.client.AerospikeClient#queryAggregate}, or {@link com.aerospike.client.AerospikeClient#queryPartitions}. Set a {@link Filter} for index query; omit filter for full namespace/set scan.
+ * <p>Build a statement with filter and run a query.</p>
+ * <pre>{@code
+ * IAerospikeClient client = new AerospikeClient("localhost", 3000);
+ * Statement stmt = new Statement();
+ * stmt.setNamespace("test");
+ * stmt.setSetName("set1");
+ * stmt.setFilter(Filter.equal("status", "active"));
+ * RecordSet rs = client.query(null, stmt);
+ * try {
+ *   while (rs.next()) {
+ *     KeyRecord kr = rs.getKeyRecord();
+ *     if (kr.record != null) { Object v = kr.record.getValue("mybin"); }
+ *   }
+ * } finally {
+ *   rs.close();
+ * }
+ * client.close();
+ * }</pre>
+ *
+ * @see Filter
+ * @see RecordSet
+ * @see ResultSet
+ * @see QueryListener
+ * @see com.aerospike.client.AerospikeClient#query
+ * @see com.aerospike.client.AerospikeClient#queryAggregate
+ * @see com.aerospike.client.AerospikeClient#queryPartitions
  */
 public final class Statement {
 	String namespace;
diff --git a/client/src/com/aerospike/client/task/Task.java b/client/src/com/aerospike/client/task/Task.java
index f596229fb..e9e73ba6e 100644
--- a/client/src/com/aerospike/client/task/Task.java
+++ b/client/src/com/aerospike/client/task/Task.java
@@ -25,11 +25,32 @@
 import com.aerospike.client.util.Util;
 
 /**
- * Task used to poll for server task completion.
+ * Base type for asynchronous server tasks (index create/drop, UDF register, background execute); poll with {@link #queryStatus()} or block with {@link #waitTillComplete()}.
+ * <p>
+ * Concrete types are returned by {@link com.aerospike.client.AerospikeClient#createIndex}, {@link com.aerospike.client.AerospikeClient#dropIndex},
+ * {@link com.aerospike.client.AerospikeClient#register}, and {@link com.aerospike.client.AerospikeClient#execute}.
+ *
+ * <p><b>Example:</b>
+ * <p>Create an index and wait for the task to complete.</p>
+ * <pre>{@code
+ * Task task = client.createIndex(null, "test", "users", "idx_status", "status", IndexType.STRING);
+ * task.waitTillComplete();
+ * }</pre>
+ *
+ * @see IndexTask
+ * @see RegisterTask
+ * @see ExecuteTask
+ * @see com.aerospike.client.AerospikeClient#createIndex
+ * @see com.aerospike.client.AerospikeClient#dropIndex
+ * @see com.aerospike.client.AerospikeClient#register
+ * @see com.aerospike.client.AerospikeClient#execute
  */
 public abstract class Task {
+	/** Task not found on server. */
 	public static final int NOT_FOUND = 0;
+	/** Task still in progress. */
 	public static final int IN_PROGRESS = 1;
+	/** Task completed. */
 	public static final int COMPLETE = 2;
 
 	protected final Cluster cluster;