fix some text in comments.

Summary:
1. Remove redundant text.
2. Make terminology consistent across all comments and doc of RocksDB. Also do
   our best to conform to conventions. Specifically, use 'callback' instead of
   'call-back' [wikipedia](https://en.wikipedia.org/wiki/Callback_(computer_programming)).
Closes https://github.com/facebook/rocksdb/pull/3693

Differential Revision: D7560396

Pulled By: riversand963

fbshipit-source-id: ba8c251c487f4e7d1872a1a8dc680f9e35a6ffb8

db/db_impl_compaction_flush.cc

@@ -2073,8 +2073,7 @@ bool DBImpl::MCOverlap(ManualCompactionState* m, ManualCompactionState* m1) {
 }
 
 // SuperVersionContext gets created and destructed outside of the lock --
-// we
+// we use this conveniently to:
-// use this convinently to:
 // * malloc one SuperVersion() outside of the lock -- new_superversion
 // * delete SuperVersion()s outside of the lock -- superversions_to_free
 //

db/listener_test.cc

@@ -260,7 +260,7 @@ TEST_F(EventListenerTest, OnSingleDBFlushTest) {
     ASSERT_EQ(listener->flushed_column_family_names_.size(), i);
   }
 
-  // make sure call-back functions are called in the right order
+  // make sure callback functions are called in the right order
   for (size_t i = 0; i < cf_names.size(); ++i) {
     ASSERT_EQ(listener->flushed_dbs_[i], db_);
     ASSERT_EQ(listener->flushed_column_family_names_[i], cf_names[i]);
@@ -296,7 +296,7 @@ TEST_F(EventListenerTest, MultiCF) {
     ASSERT_EQ(listener->flushed_column_family_names_.size(), i);
   }
 
-  // make sure call-back functions are called in the right order
+  // make sure callback functions are called in the right order
   for (size_t i = 0; i < cf_names.size(); i++) {
     ASSERT_EQ(listener->flushed_dbs_[i], db_);
     ASSERT_EQ(listener->flushed_column_family_names_[i], cf_names[i]);

include/rocksdb/listener.h

@@ -230,12 +230,12 @@ struct ExternalFileIngestionInfo {
   TableProperties table_properties;
 };
 
-// EventListener class contains a set of call-back functions that will
+// EventListener class contains a set of callback functions that will
 // be called when specific RocksDB event happens such as flush.  It can
 // be used as a building block for developing custom features such as
 // stats-collector or external compaction algorithm.
 //
-// Note that call-back functions should not run for an extended period of
+// Note that callback functions should not run for an extended period of
 // time before the function returns, otherwise RocksDB may be blocked.
 // For example, it is not suggested to do DB::CompactFiles() (as it may
 // run for a long while) or issue many of DB::Put() (as Put may be blocked
@@ -251,17 +251,10 @@ struct ExternalFileIngestionInfo {
 // [Locking] All EventListener callbacks are designed to be called without
 // the current thread holding any DB mutex. This is to prevent potential
 // deadlock and performance issue when using EventListener callback
-// in a complex way. However, all EventListener call-back functions
+// in a complex way.
-// should not run for an extended period of time before the function
-// returns, otherwise RocksDB may be blocked. For example, it is not
-// suggested to do DB::CompactFiles() (as it may run for a long while)
-// or issue many of DB::Put() (as Put may be blocked in certain cases)
-// in the same thread in the EventListener callback. However, doing
-// DB::CompactFiles() and DB::Put() in a thread other than the
-// EventListener callback thread is considered safe.
 class EventListener {
  public:
-  // A call-back function to RocksDB which will be called whenever a
+  // A callback function to RocksDB which will be called whenever a
   // registered RocksDB flushes a file.  The default implementation is
   // no-op.
   //
@@ -271,7 +264,7 @@ class EventListener {
   virtual void OnFlushCompleted(DB* /*db*/,
                                 const FlushJobInfo& /*flush_job_info*/) {}
 
-  // A call-back function to RocksDB which will be called before a
+  // A callback function to RocksDB which will be called before a
   // RocksDB starts to flush memtables.  The default implementation is
   // no-op.
   //
@@ -281,9 +274,9 @@ class EventListener {
   virtual void OnFlushBegin(DB* /*db*/,
                             const FlushJobInfo& /*flush_job_info*/) {}
 
-  // A call-back function for RocksDB which will be called whenever
+  // A callback function for RocksDB which will be called whenever
   // a SST file is deleted.  Different from OnCompactionCompleted and
-  // OnFlushCompleted, this call-back is designed for external logging
+  // OnFlushCompleted, this callback is designed for external logging
   // service and thus only provide string parameters instead
   // of a pointer to DB.  Applications that build logic basic based
   // on file creations and deletions is suggested to implement
@@ -294,7 +287,7 @@ class EventListener {
   // returned value.
   virtual void OnTableFileDeleted(const TableFileDeletionInfo& /*info*/) {}
 
-  // A call-back function for RocksDB which will be called whenever
+  // A callback function for RocksDB which will be called whenever
   // a registered RocksDB compacts a file. The default implementation
   // is a no-op.
   //
@@ -310,9 +303,9 @@ class EventListener {
   virtual void OnCompactionCompleted(DB* /*db*/,
                                      const CompactionJobInfo& /*ci*/) {}
 
-  // A call-back function for RocksDB which will be called whenever
+  // A callback function for RocksDB which will be called whenever
   // a SST file is created.  Different from OnCompactionCompleted and
-  // OnFlushCompleted, this call-back is designed for external logging
+  // OnFlushCompleted, this callback is designed for external logging
   // service and thus only provide string parameters instead
   // of a pointer to DB.  Applications that build logic basic based
   // on file creations and deletions is suggested to implement
@@ -327,7 +320,7 @@ class EventListener {
   // returned value.
   virtual void OnTableFileCreated(const TableFileCreationInfo& /*info*/) {}
 
-  // A call-back function for RocksDB which will be called before
+  // A callback function for RocksDB which will be called before
   // a SST file is being created. It will follow by OnTableFileCreated after
   // the creation finishes.
   //
@@ -337,7 +330,7 @@ class EventListener {
   virtual void OnTableFileCreationStarted(
       const TableFileCreationBriefInfo& /*info*/) {}
 
-  // A call-back function for RocksDB which will be called before
+  // A callback function for RocksDB which will be called before
   // a memtable is made immutable.
   //
   // Note that the this function must be implemented in a way such that
@@ -350,7 +343,7 @@ class EventListener {
   virtual void OnMemTableSealed(
     const MemTableInfo& /*info*/) {}
 
-  // A call-back function for RocksDB which will be called before
+  // A callback function for RocksDB which will be called before
   // a column family handle is deleted.
   //
   // Note that the this function must be implemented in a way such that
@@ -361,7 +354,7 @@ class EventListener {
   virtual void OnColumnFamilyHandleDeletionStarted(
       ColumnFamilyHandle* /*handle*/) {}
 
-  // A call-back function for RocksDB which will be called after an external
+  // A callback function for RocksDB which will be called after an external
   // file is ingested using IngestExternalFile.
   //
   // Note that the this function will run on the same thread as
@@ -370,7 +363,7 @@ class EventListener {
   virtual void OnExternalFileIngested(
       DB* /*db*/, const ExternalFileIngestionInfo& /*info*/) {}
 
-  // A call-back function for RocksDB which will be called before setting the
+  // A callback function for RocksDB which will be called before setting the
   // background error status to a non-OK value. The new background error status
   // is provided in `bg_error` and can be modified by the callback. E.g., a
   // callback can suppress errors by resetting it to Status::OK(), thus
@@ -384,7 +377,7 @@ class EventListener {
   virtual void OnBackgroundError(BackgroundErrorReason /* reason */,
                                  Status* /* bg_error */) {}
 
-  // A call-back function for RocksDB which will be called whenever a change
+  // A callback function for RocksDB which will be called whenever a change
   // of superversion triggers a change of the stall conditions.
   //
   // Note that the this function must be implemented in a way such that

include/rocksdb/options.h

@@ -423,7 +423,7 @@ struct DBOptions {
 
   // By default, writes to stable storage use fdatasync (on platforms
   // where this function is available). If this option is true,
-  // fsync is used instead. 
+  // fsync is used instead.
   //
   // fsync and fdatasync are equally safe for our purposes and fdatasync is
   // faster, so it is rarely necessary to set this option. It is provided
@@ -753,7 +753,7 @@ struct DBOptions {
   // Default: 0, turned off
   uint64_t wal_bytes_per_sync = 0;
 
-  // A vector of EventListeners which call-back functions will be called
+  // A vector of EventListeners which callback functions will be called
   // when specific RocksDB event happens.
   std::vector<std::shared_ptr<EventListener>> listeners;
 

options/cf_options.h

@@ -109,7 +109,7 @@ struct ImmutableCFOptions {
 
   bool preserve_deletes;
 
-  // A vector of EventListeners which call-back functions will be called
+  // A vector of EventListeners which callback functions will be called
   // when specific RocksDB event happens.
   std::vector<std::shared_ptr<EventListener>> listeners;
 

third-party/fbson/FbsonDocument.h

@@ -48,7 +48,7 @@
  * and use index to retrieve from array. Array index is 0-based.
  *
  * ** External dictionary **
- * During query processing, you can also pass a call-back function, so the
+ * During query processing, you can also pass a callback function, so the
  * search will first try to check if the key string exists in the dictionary.
  * If so, search will be based on the id instead of the key string.
  *

third-party/fbson/FbsonJsonParser.h

@@ -31,7 +31,7 @@
  * FbsonErrType, and can be retrieved by calling getErrorCode().
  *
  * ** External dictionary **
- * During parsing a JSON string, you can pass a call-back function to map a key
+ * During parsing a JSON string, you can pass a callback function to map a key
  * string to an id, and store the dictionary id in FBSON to save space. The
  * purpose of using an external dictionary is more towards a collection of
  * documents (which has common keys) rather than a single document, so that