Merge pull request #2457 from gauravvnera/doc_blitz_clear_range

DocBlitz : Clarify Documentation for clear_range API

bindings/go/src/fdb/transaction.go

@@ -337,6 +337,11 @@ func (t Transaction) Clear(key KeyConvertible) {
 // ClearRange removes all keys k such that begin <= k < end, and their
 // associated values. ClearRange returns immediately, having modified the
 // snapshot of the database represented by the transaction.
+// Range clears are efficient with FoundationDB -- clearing large amounts of data
+// will be fast. However, this will not immediately free up disk -
+// data for the deleted range is cleaned up in the background.
+// For purposes of computing the transaction size, only the begin and end keys of a clear range are counted.
+// The size of the data stored in the range does not count against the transaction size limit.
 func (t Transaction) ClearRange(er ExactRange) {
 	begin, end := er.FDBRangeKeys()
 	bkb := begin.FDBKey()

bindings/java/src/main/com/apple/foundationdb/Transaction.java

@@ -157,7 +157,13 @@ public interface Transaction extends AutoCloseable, ReadTransaction, Transaction
 	 *  exclusive; that is, the key (if one exists) that is specified as the end
 	 *  of the range will NOT be cleared as part of this operation.  Range clears are
 	 *  efficient with FoundationDB -- clearing large amounts of data will be fast.
+	 *  However, this will not immediately free up disk - data for the deleted range
+	 *  is cleaned up in the background.
 	 *  This will not affect the database until {@link #commit} is called.
+	 *  <br>
+	 *  For purposes of computing the transaction size, only the begin and end keys of a clear range are counted.
+	 *  The size of the data stored in the range does not count against the transaction size limit.
+	 *
 	 *
 	 * @param range the range of keys to clear
 	 *

documentation/sphinx/source/api-c.rst

@@ -601,6 +601,8 @@ Applications must provide error handling and an appropriate retry loop around th
 
    |sets-and-clears2|
 
+   |transaction-clear-range-blurb|
+
    ``begin_key_name``
       A pointer to the name of the key specifying the beginning of the range to clear. |no-null|
 

documentation/sphinx/source/api-common.rst.inc

@@ -192,6 +192,10 @@
 
     By default, each database connection can have no more than 10,000 watches that have not yet reported a change. When this number is exceeded, an attempt to create a watch will |error-raise-type| a :ref:`too_many_watches <developer-guide-error-codes>` |error-type|. This limit can be changed using |max-watches-database-option|. Because a watch outlives the transaction that creates it, any watch that is no longer needed should be cancelled by calling |future-cancel| on its returned future.
 
+.. |transaction-clear-range-blurb| replace::
+
+    Range clears are efficient with FoundationDB -- clearing large amounts of data will be fast. However, this will not immediately free up disk - data for the deleted range is cleaned up in the background. For purposes of computing the transaction size, only the begin and end keys of a clear range are counted. The size of the data stored in the range does not count against the transaction size limit.
+
 .. |conflict-range-note| replace::
 
     Most applications will use the strictly serializable isolation that transactions provide by default and will not need to manipulate conflict ranges.

documentation/sphinx/source/api-python.rst

@@ -591,6 +591,8 @@ Writing data
 
     Removes all keys ``k`` such that ``begin <= k < end``, and their associated values. |immediate-return|
 
+    |transaction-clear-range-blurb|
+
     .. note :: Unlike in the case of :meth:`get_range`, ``begin`` and ``end`` must be keys (byte strings), not :class:`KeySelector`\ s.  (Resolving arbitrary key selectors would prevent this method from returning immediately, introducing concurrency issues.)
 
 ``del tr[begin:end]``
@@ -600,6 +602,8 @@ Writing data
 
     Removes all the keys ``k`` such that ``k.startswith(prefix)``, and their associated values. |immediate-return|
 
+    |transaction-clear-range-blurb|
+
 .. _api-python-transaction-atomic-operations:
 
 Atomic operations

documentation/sphinx/source/api-ruby.rst

@@ -548,12 +548,16 @@ Writing data
 
     Removes all keys ``k`` such that ``begin <= k < end``, and their associated values. |immediate-return|
 
+    |transaction-clear-range-blurb|
+
     .. note:: Unlike in the case of :meth:`Transaction.get_range`, ``begin`` and ``end`` must be keys (:class:`String` or :class:`Key`), not :class:`KeySelector`\ s.  (Resolving arbitrary key selectors would prevent this method from returning immediately, introducing concurrency issues.)
 
 .. method:: Transaction.clear_range_start_with(prefix) -> nil
 
     Removes all the keys ``k`` such that ``k.start_with? prefix``, and their associated values. |immediate-return|
 
+    |transaction-clear-range-blurb|
+
 .. _api-ruby-transaction-atomic-operations:
 
 Atomic operations