Add/improve misc comments (#8963)

Summary:
Fill in some missing info; fix some incorrect info.

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

Test Plan: comments only

Reviewed By: mrambacher

Differential Revision: D31211183

Pulled By: pdillinger

fbshipit-source-id: 783ff6673791c01d44c3ed92d4398c64ae5a5005

include/rocksdb/db.h

@@ -1517,9 +1517,10 @@ class DB {
   // Option in import_options specifies whether the external files are copied or
   // moved (default is copy). When option specifies copy, managing files at
   // external_file_path is caller's responsibility. When option specifies a
-  // move, the call ensures that the specified files at external_file_path are
-  // deleted on successful return and files are not modified on any error
-  // return.
+  // move, the call makes a best effort to delete the specified files at
+  // external_file_path on successful return, logging any failure to delete
+  // rather than returning in Status. Files are not modified on any error
+  // return, and a best effort is made to remove any newly-created files.
   // On error return, column family handle returned will be nullptr.
   // ColumnFamily will be present on successful return and will not be present
   // on error return. ColumnFamily may be present on any crash during this call.

include/rocksdb/env.h

@@ -1800,6 +1800,8 @@ Env* NewTimedEnv(Env* base_env);
 Status NewEnvLogger(const std::string& fname, Env* env,
                     std::shared_ptr<Logger>* result);
 
+// Creates a new Env based on Env::Default() but modified to use the specified
+// FileSystem.
 std::unique_ptr<Env> NewCompositeEnv(const std::shared_ptr<FileSystem>& fs);
 
 }  // namespace ROCKSDB_NAMESPACE

include/rocksdb/file_system.h

@@ -196,6 +196,8 @@ struct IODebugContext {
 // of the APIs is of type IOStatus, which can indicate an error code/sub-code,
 // as well as metadata about the error such as its scope and whether its
 // retryable.
+// NewCompositeEnv can be used to create an Env with a custom FileSystem for
+// DBOptions::env.
 class FileSystem {
  public:
   FileSystem();
@@ -228,11 +230,8 @@ class FileSystem {
                                  const std::string& value,
                                  std::shared_ptr<FileSystem>* result);
 
-  // Return a default fie_system suitable for the current operating
-  // system.  Sophisticated users may wish to provide their own Env
-  // implementation instead of relying on this default file_system
-  //
-  // The result of Default() belongs to rocksdb and must never be deleted.
+  // Return a default FileSystem suitable for the current operating
+  // system.
   static std::shared_ptr<FileSystem> Default();
 
   // Handles the event when a new DB or a new ColumnFamily starts using the

include/rocksdb/slice_transform.h

@@ -67,7 +67,7 @@ class SliceTransform : public Customizable {
   // prefix size of 4.
   //
   // Wiki documentation here:
-  // https://github.com/facebook/rocksdb/wiki/Prefix-Seek-API-Changes
+  // https://github.com/facebook/rocksdb/wiki/Prefix-Seek
   //
   virtual bool InDomain(const Slice& key) const = 0;
 
@@ -107,10 +107,15 @@ class SliceTransform : public Customizable {
   }
 };
 
+// The prefix is the first `prefix_len` bytes of the key, and keys shorter
+// then `prefix_len` are not InDomain.
 extern const SliceTransform* NewFixedPrefixTransform(size_t prefix_len);
 
+// The prefix is the first min(length(key),`cap_len`) bytes of the key, and
+// all keys are InDomain.
 extern const SliceTransform* NewCappedPrefixTransform(size_t cap_len);
 
+// Prefix is equal to key. All keys are InDomain.
 extern const SliceTransform* NewNoopTransform();
 
 }  // namespace ROCKSDB_NAMESPACE