Specify precedence in `SstFileWriter::DeleteRange()` API contract (#11309)

Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/11309

Reviewed By: cbi42

Differential Revision: D44198501

Pulled By: ajkr

fbshipit-source-id: d603aca37b56aac5df255833793a3300807d63cf

db/external_sst_file_basic_test.cc

@@ -102,7 +102,8 @@ class ExternalSSTFileBasicTest
       // all point operators, even though sst_file_writer.DeleteRange
       // must be called before other sst_file_writer methods. This is
       // because point writes take precedence over range deletions
-      // in the same ingested sst.
+      // in the same ingested sst. This precedence is part of
+      // `SstFileWriter::DeleteRange()`'s API contract.
       std::string start_key = Key(range_deletions[i].first);
       std::string end_key = Key(range_deletions[i].second);
       s = sst_file_writer.DeleteRange(start_key, end_key);

include/rocksdb/sst_file_writer.h

@@ -143,11 +143,13 @@ class SstFileWriter {
   // the comparator.
   Status Delete(const Slice& user_key, const Slice& timestamp);
 
-  // Add a range deletion tombstone to currently opened file
+  // Add a range deletion tombstone to currently opened file. Such a range
+  // deletion tombstone does NOT delete other (point) keys in the same file.
   // REQUIRES: comparator is *not* timestamp-aware.
   Status DeleteRange(const Slice& begin_key, const Slice& end_key);
 
-  // Add a range deletion tombstone to currently opened file.
+  // Add a range deletion tombstone to currently opened file. Such a range
+  // deletion tombstone does NOT delete other (point) keys in the same file.
   // REQUIRES: begin_key and end_key are user keys without timestamp.
   // REQUIRES: the timestamp's size is equal to what is expected by
   // the comparator.