Document how "next_random" cursors really work.

3 files changed, 19 insertions, 2 deletions

diff --git a/dist/api_data.py b/dist/api_data.py
index 9f8cdf62d88..9d9804b3a94 100644
--- a/dist/api_data.py
+++ b/dist/api_data.py
@@ -286,7 +286,8 @@ methods = {
 		configure the cursor to return a pseudo-random record from
 		the object; valid only for row-store cursors.  Cursors
 		configured with next_random only support the WT_CURSOR::next
-		and WT_CURSOR::close methods''',
+		and WT_CURSOR::close methods.  See @ref cursor_random for
+		details''',
 		type='boolean'),
 	Config('overwrite', 'false', r'''
 		change the behavior of the cursor's insert method to overwrite
diff --git a/src/docs/cursor-random.dox b/src/docs/cursor-random.dox
new file mode 100644
index 00000000000..f7940175f22
--- /dev/null
+++ b/src/docs/cursor-random.dox
@@ -0,0 +1,15 @@
+/*! @page cursor_random Cursor random
+
+The \c next_random configuration to the WT_SESSION::open_cursor method
+configures the cursor to return a pseudo-random record from a row-store
+object.  The ability to return a random record was added to support a
+particular application, and as a result has somewhat unusual semantics.
+First, the returned record may not be random at all in the case of
+objects with only a few rows (especially when the object has never been
+written to the backing store).  In such objects, the WT_CURSOR::next
+method for cursors configured with \c next_random may return the same
+row on each call.  Additionally, even in larger objects, the
+WT_CURSOR::next method usually returns the first record from a random
+page in the underlying file, not a random record from a random page.
+
+ */
diff --git a/src/include/wiredtiger.in b/src/include/wiredtiger.in
index c52cb2b56b7..c7cb00fb2ba 100644
--- a/src/include/wiredtiger.in
+++ b/src/include/wiredtiger.in
@@ -540,7 +540,8 @@ struct __wt_session {
 	 * @config{next_random, configure the cursor to return a pseudo-random
 	 * record from the object; valid only for row-store cursors.  Cursors
 	 * configured with next_random only support the WT_CURSOR::next and
-	 * WT_CURSOR::close methods.,a boolean flag; default \c false.}
+	 * WT_CURSOR::close methods.  See @ref cursor_random for details.,a
+	 * boolean flag; default \c false.}
 	 * @config{overwrite, change the behavior of the cursor's insert method
 	 * to overwrite previously existing values.,a boolean flag; default \c
 	 * false.}