Add some documentation for Env related interfaces (#12813)

Summary:
As titled. Added some documentations for some `Env` interfaces and removed some obsolete doc for `Options.env`.

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

Reviewed By: ajkr

Differential Revision: D59119632

Pulled By: jowlyzhang

fbshipit-source-id: 114b13f0f843cde6ebc0746156b80c94ea2ce143

env/composite_env_wrapper.h

@@ -18,6 +18,13 @@
 
 namespace ROCKSDB_NAMESPACE {
 
+// This class supports abstracting different types of an `Env`'s functionality
+// into separate interfaces. It is constructed with a `FileSystem` and a
+// `SystemClock` and delegates:
+// * File system operations to member `file_system_`.
+// * Time related misc operations to member `clock_`.
+// A subclass needs to inherit `CompositeEnv` and provide implementations for
+// the thread management related APIs.
 class CompositeEnv : public Env {
  public:
   // Initialize a CompositeEnvWrapper that delegates all thread/time related
@@ -250,6 +257,20 @@ class CompositeEnv : public Env {
   }
 };
 
+// A `CompositeEnvWrapper` is constructed with a target `Env` object, an
+// optional `FileSystem` object and an optional `SystemClock` object.
+// `Env::GetFileSystem()` is a fallback file system if no such object is
+// explicitly provided. Similarly, `Env::GetSystemClock()` is a fallback system
+// clock.
+// Besides delegating corresponding functionality to `file_system_` and `clock_`
+// which is inherited from `CompositeEnv`, it also implements the thread
+// management APIs by delegating them to the target `Env` object.
+//
+// Effectively, this class helps to support using customized file system
+// implementations such as a remote file system instead of the default file
+// system provided by the operating system.
+//
+// Also see public API `NewCompositeEnv` in rocksdb/include/env.h
 class CompositeEnvWrapper : public CompositeEnv {
  public:
   // Initialize a CompositeEnvWrapper that delegates all thread/time related

env/env.cc

@@ -355,6 +355,12 @@ class LegacyDirectoryWrapper : public FSDirectory {
   std::unique_ptr<Directory> target_;
 };
 
+// A helper class to make legacy `Env` implementations be backward compatible
+// now that all `Env` implementations are expected to have a `FileSystem` type
+// member `file_system_` and a `SystemClock` type member `clock_`.
+// This class wraps a legacy `Env` object and expose its file system related
+// APIs as a `FileSystem` interface. Also check `LegacySystemClock` that does
+// the same thing for the clock related APIs.
 class LegacyFileSystemWrapper : public FileSystem {
  public:
   // Initialize an EnvWrapper that delegates all calls to *t

include/rocksdb/env.h

@@ -145,6 +145,11 @@ struct EnvOptions {
 // Exceptions MUST NOT propagate out of overridden functions into RocksDB,
 // because RocksDB is not exception-safe. This could cause undefined behavior
 // including data loss, unreported corruption, deadlocks, and more.
+// An interface that abstracts RocksDB's interactions with the operating system
+// environment. There are three main types of APIs:
+// 1) File system operations, like creating a file, writing to a file, etc.
+// 2) Thread management.
+// 3) Misc functions, like getting the current time.
 class Env : public Customizable {
  public:
   static const char* kDefaultName() { return "DefaultEnv"; }

include/rocksdb/options.h

@@ -645,9 +645,7 @@ struct DBOptions {
   bool verify_sst_unique_id_in_manifest = true;
 
   // Use the specified object to interact with the environment,
-  // e.g. to read/write files, schedule background work, etc. In the near
-  // future, support for doing storage operations such as read/write files
-  // through env will be deprecated in favor of file_system (see below)
+  // e.g. to read/write files, schedule background work, etc.
   // Default: Env::Default()
   Env* env = Env::Default();