Polishing.

Add since tags. Consistently document scan command with try-with-resources guidance. Use try-with-resources in tests.

See #2260
Original pull request: #2263.

src/main/java/org/springframework/data/redis/core/BoundHashOperations.java

@@ -202,10 +202,12 @@ public interface BoundHashOperations<H, HK, HV> extends BoundKeyOperations<H> {
 	Map<HK, HV> entries();
 
 	/**
-	 * Use a {@link Cursor} to iterate over entries in the hash.
+	 * Use a {@link Cursor} to iterate over entries in hash at the bound key. <br />
+	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leaks.
 	 *
-	 * @param options
-	 * @return
+	 * @param options must not be {@literal null}.
+	 * @return the result cursor providing access to the scan result. Must be closed once fully processed (e.g. through a
+	 *         try-with-resources clause).
 	 * @since 1.4
 	 */
 	Cursor<Map.Entry<HK, HV>> scan(ScanOptions options);

src/main/java/org/springframework/data/redis/core/BoundSetOperations.java

@@ -253,8 +253,12 @@ public interface BoundSetOperations<K, V> extends BoundKeyOperations<K> {
 	List<V> randomMembers(long count);
 
 	/**
-	 * @param options
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * Use a {@link Cursor} to iterate over entries in set at {@code key}. <br />
+	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leaks.
+	 *
+	 * @param options must not be {@literal null}.
+	 * @return the result cursor providing access to the scan result. Must be closed once fully processed (e.g. through a
+	 *         try-with-resources clause).
 	 * @since 1.4
 	 */
 	@Nullable

src/main/java/org/springframework/data/redis/core/BoundZSetOperations.java

@@ -794,11 +794,12 @@ public interface BoundZSetOperations<K, V> extends BoundKeyOperations<K> {
 	Long unionAndStore(Collection<K> otherKeys, K destKey, Aggregate aggregate);
 
 	/**
-	 * Iterate over elements in zset at the bound key. <br />
-	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leak.
+	 * Use a {@link Cursor} to iterate over entries in zset at the bound key. <br />
+	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leaks.
 	 *
-	 * @param options
-	 * @return
+	 * @param options must not be {@literal null}.
+	 * @return the result cursor providing access to the scan result. Must be closed once fully processed (e.g. through a
+	 *         try-with-resources clause).
 	 * @since 1.4
 	 */
 	Cursor<TypedTuple<V>> scan(ScanOptions options);

src/main/java/org/springframework/data/redis/core/HashOperations.java

@@ -210,11 +210,12 @@ public interface HashOperations<H, HK, HV> {
 
 	/**
 	 * Use a {@link Cursor} to iterate over entries in hash at {@code key}. <br />
-	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leak.
+	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leaks.
 	 *
 	 * @param key must not be {@literal null}.
-	 * @param options
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @param options must not be {@literal null}.
+	 * @return the result cursor providing access to the scan result. Must be closed once fully processed (e.g. through a
+	 *         try-with-resources clause).
 	 * @since 1.4
 	 */
 	Cursor<Map.Entry<HK, HV>> scan(H key, ScanOptions options);

src/main/java/org/springframework/data/redis/core/RedisOperations.java

@@ -262,10 +262,12 @@ public interface RedisOperations<K, V> {
 
 	/**
 	 * Use a {@link Cursor} to iterate over keys. <br />
-	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leak.
+	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leaks.
 	 *
 	 * @param options must not be {@literal null}.
-	 * @return never {@literal null}.
+	 * @return the result cursor providing access to the scan result. Must be closed once fully processed (e.g. through a
+	 *         try-with-resources clause).
+	 * @since 2.7
 	 * @see <a href="https://redis.io/commands/scan">Redis Documentation: SCAN</a>
 	 */
 	Cursor<K> scan(ScanOptions options);

src/main/java/org/springframework/data/redis/core/SetOperations.java

@@ -372,12 +372,13 @@ public interface SetOperations<K, V> {
 	List<V> randomMembers(K key, long count);
 
 	/**
-	 * Iterate over elements in set at {@code key}. <br />
-	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leak.
+	 * Use a {@link Cursor} to iterate over entries set at {@code key}. <br />
+	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leaks.
 	 *
 	 * @param key
-	 * @param options
-	 * @return
+	 * @param options must not be {@literal null}.
+	 * @return the result cursor providing access to the scan result. Must be closed once fully processed (e.g. through a
+	 *         try-with-resources clause).
 	 * @since 1.4
 	 */
 	Cursor<V> scan(K key, ScanOptions options);

src/main/java/org/springframework/data/redis/core/ZSetOperations.java

@@ -947,12 +947,13 @@ public interface ZSetOperations<K, V> {
 	Long unionAndStore(K key, Collection<K> otherKeys, K destKey, Aggregate aggregate, Weights weights);
 
 	/**
-	 * Iterate over elements in zset at {@code key}. <br />
-	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leak.
+	 * Use a {@link Cursor} to iterate over entries zset at {@code key}. <br />
+	 * <strong>Important:</strong> Call {@link Cursor#close()} when done to avoid resource leaks.
 	 *
 	 * @param key
-	 * @param options
-	 * @return {@literal null} when used in pipeline / transaction.
+	 * @param options must not be {@literal null}.
+	 * @return the result cursor providing access to the scan result. Must be closed once fully processed (e.g. through a
+	 *         try-with-resources clause).
 	 * @see <a href="https://redis.io/commands/zscan">Redis Documentation: ZSCAN</a>
 	 * @since 1.4
 	 */