Update API comment about Options::best_efforts_recovery (#10180)

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

Reviewed By: pdillinger

Differential Revision: D37182037

Pulled By: riversand963

fbshipit-source-id: a8dc865b86e2249beb7a543c317e94a14781e910

include/rocksdb/options.h

@@ -1274,13 +1274,30 @@ struct DBOptions {
   // Default: nullptr
   std::shared_ptr<FileChecksumGenFactory> file_checksum_gen_factory = nullptr;
 
-  // By default, RocksDB recovery fails if any table file referenced in
-  // MANIFEST are missing after scanning the MANIFEST.
-  // Best-efforts recovery is another recovery mode that
-  // tries to restore the database to the most recent point in time without
-  // missing file.
-  // Currently not compatible with atomic flush. Furthermore, WAL files will
+  // By default, RocksDB recovery fails if any table/blob file referenced in
+  // MANIFEST are missing after scanning the MANIFEST pointed to by the
+  // CURRENT file.
+  // Best-efforts recovery is another recovery mode that tolerates missing or
+  // corrupted table or blob files.
+  // Best-efforts recovery does not need a valid CURRENT file, and tries to
+  // recover the database using one of the available MANIFEST files in the db
+  // directory.
+  // Best-efforts recovery recovers database to a state in which the database
+  // includes only table and blob files whose actual sizes match the
+  // information in the chosen MANIFEST without holes in the history.
+  // Best-efforts recovery tries the available MANIFEST files from high file
+  // numbers (newer) to low file numbers (older), and stops after finding the
+  // first MANIFEST file from which the db can be recovered to a state without
+  // invalid (missing/file-mismatch) table and blob files.
+  // It is possible that the database can be restored to an empty state with no
+  // table or blob files.
+  // Regardless of this option, the IDENTITY file is updated if needed during
+  // recovery to match the DB ID in the MANIFEST (if previously using
+  // write_dbid_to_manifest) or to be in some valid state (non-empty DB ID).
+  // Currently, not compatible with atomic flush. Furthermore, WAL files will
   // not be used for recovery if best_efforts_recovery is true.
+  // Also requires either 1) LOCK file exists or 2) underlying env's LockFile()
+  // call returns ok even for non-existing LOCK file.
   // Default: false
   bool best_efforts_recovery = false;