Document SingleDelete

Summary: Docuemented what is currently supported by SingleDelete based on its current implementation.

Test Plan: n/a

Reviewers: sdong, kradhakrishnan, yhchiang, rven

Reviewed By: rven

Subscribers: dhruba, leveldb

Differential Revision: https://reviews.facebook.net/D50205

include/rocksdb/db.h

@@ -189,6 +189,18 @@ class DB {
   // Remove the database entry for "key". Requires that the key exists
   // and was not overwritten. Returns OK on success, and a non-OK status
   // on error.  It is not an error if "key" did not exist in the database.
+  //
+  // If a key is overwritten (by calling Put() multiple times), then the result
+  // of calling SingleDelete() on this key is undefined.  SingleDelete() only
+  // behaves correctly if there has been only one Put() for this key since the
+  // previous call to SingleDelete() for this key.
+  //
+  // This feature is currently an experimental performance optimization
+  // for a very specific workload.  It is up to the caller to ensure that
+  // SingleDelete is only used for a key that is not deleted using Delete() or
+  // written using Merge().  Mixing SingleDelete operations with Deletes and
+  // Merges can result in undefined behavior.
+  //
   // Note: consider setting options.sync = true.
   virtual Status SingleDelete(const WriteOptions& options,
                               ColumnFamilyHandle* column_family,

include/rocksdb/write_batch.h

@@ -71,8 +71,7 @@ class WriteBatch : public WriteBatchBase {
   void Delete(const SliceParts& key) override { Delete(nullptr, key); }
 
   using WriteBatchBase::SingleDelete;
-  // If the database contains a mapping for "key", erase it. Expects that the
-  // key was not overwritten. Else do nothing.
+  // WriteBatch implementation of DB::SingleDelete().  See db.h.
   void SingleDelete(ColumnFamilyHandle* column_family,
                     const Slice& key) override;
   void SingleDelete(const Slice& key) override { SingleDelete(nullptr, key); }