Add comments describing {Put,Get}Entity, update/clarify comment for Get and iterator (#10676)

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

Reviewed By: riversand963

Differential Revision: D39512081

Pulled By: ltamasi

fbshipit-source-id: 55704478ceb8081003eceeb0c5a3875cb806587e

include/rocksdb/db.h

@@ -407,7 +407,11 @@ class DB {
     return Put(options, DefaultColumnFamily(), key, ts, value);
   }
 
-  // UNDER CONSTRUCTION -- DO NOT USE
+  // Set the database entry for "key" in the column family specified by
+  // "column_family" to the wide-column entity defined by "columns". If the key
+  // already exists in the column family, it will be overwritten.
+  //
+  // Returns OK on success, and a non-OK status on error.
   virtual Status PutEntity(const WriteOptions& options,
                            ColumnFamilyHandle* column_family, const Slice& key,
                            const WideColumns& columns);
@@ -511,16 +515,17 @@ class DB {
   // Note: consider setting options.sync = true.
   virtual Status Write(const WriteOptions& options, WriteBatch* updates) = 0;
 
-  // If the database contains an entry for "key" store the
+  // If the column family specified by "column_family" contains an entry for
-  // corresponding value in *value and return OK.
+  // "key", return the corresponding value in "*value". If the entry is a plain
+  // key-value, return the value as-is; if it is a wide-column entity, return
+  // the value of its default anonymous column (see kDefaultWideColumnName) if
+  // any, or an empty value otherwise.
   //
   // If timestamp is enabled and a non-null timestamp pointer is passed in,
   // timestamp is returned.
   //
-  // If there is no entry for "key" leave *value unchanged and return
+  // Returns OK on success. Returns NotFound and an empty value in "*value" if
-  // a status for which Status::IsNotFound() returns true.
+  // there is no entry for "key". Returns some other non-OK status on error.
-  //
-  // May return some other Status on an error.
   virtual inline Status Get(const ReadOptions& options,
                             ColumnFamilyHandle* column_family, const Slice& key,
                             std::string* value) {
@@ -567,7 +572,15 @@ class DB {
     return Get(options, DefaultColumnFamily(), key, value, timestamp);
   }
 
-  // UNDER CONSTRUCTION -- DO NOT USE
+  // If the column family specified by "column_family" contains an entry for
+  // "key", return it as a wide-column entity in "*columns". If the entry is a
+  // wide-column entity, return it as-is; if it is a plain key-value, return it
+  // as an entity with a single anonymous column (see kDefaultWideColumnName)
+  // which contains the value.
+  //
+  // Returns OK on success. Returns NotFound and an empty wide-column entity in
+  // "*columns" if there is no entry for "key". Returns some other non-OK status
+  // on error.
   virtual Status GetEntity(const ReadOptions& /* options */,
                            ColumnFamilyHandle* /* column_family */,
                            const Slice& /* key */,

include/rocksdb/iterator.h

@@ -81,17 +81,21 @@ class Iterator : public Cleanable {
   // REQUIRES: Valid()
   virtual Slice key() const = 0;
 
-  // Return the value for the current entry.  The underlying storage for
+  // Return the value for the current entry.  If the entry is a plain key-value,
-  // the returned slice is valid only until the next modification of the
+  // return the value as-is; if it is a wide-column entity, return the value of
-  // iterator (i.e. the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev
+  // the default anonymous column (see kDefaultWideColumnName) if any, or an
-  // operation).
+  // empty value otherwise.  The underlying storage for the returned slice is
+  // valid only until the next modification of the iterator (i.e. the next
+  // SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev operation).
   // REQUIRES: Valid()
   virtual Slice value() const = 0;
 
-  // Return the wide columns for the current entry.  The underlying storage for
+  // Return the wide columns for the current entry.  If the entry is a
-  // the returned structure is valid only until the next modification of the
+  // wide-column entity, return it as-is; if it is a plain key-value, return it
-  // iterator (i.e. the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev
+  // as an entity with a single anonymous column (see kDefaultWideColumnName)
-  // operation).
+  // which contains the value.  The underlying storage for the returned
+  // structure is valid only until the next modification of the iterator (i.e.
+  // the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev operation).
   // REQUIRES: Valid()
   virtual const WideColumns& columns() const {
     assert(false);

include/rocksdb/write_batch.h

@@ -100,7 +100,8 @@ class WriteBatch : public WriteBatchBase {
     return Put(nullptr, key, value);
   }
 
-  // UNDER CONSTRUCTION -- DO NOT USE
+  // Store the mapping "key->{column1:value1, column2:value2, ...}" in the
+  // column family specified by "column_family".
   using WriteBatchBase::PutEntity;
   Status PutEntity(ColumnFamilyHandle* column_family, const Slice& key,
                    const WideColumns& columns) override;

include/rocksdb/write_batch_base.h

@@ -42,7 +42,8 @@ class WriteBatchBase {
                      const SliceParts& value);
   virtual Status Put(const SliceParts& key, const SliceParts& value);
 
-  // UNDER CONSTRUCTION -- DO NOT USE
+  // Store the mapping "key->{column1:value1, column2:value2, ...}" in the
+  // column family specified by "column_family".
   virtual Status PutEntity(ColumnFamilyHandle* column_family, const Slice& key,
                            const WideColumns& columns) = 0;