improve comments for CrateRateLimiter()

Summary:
Suggested by @dhruba from the other diff, here is the improved
comments for parameters of the function

Test Plan: none

Reviewers: dhruba, sdong, igor

Reviewed By: igor

Subscribers: dhruba, leveldb

Differential Revision: https://reviews.facebook.net/D19623

include/rocksdb/options.h

@@ -1030,12 +1030,22 @@ struct FlushOptions {
 
 // Create a RateLimiter object, which can be shared among RocksDB instances to
 // control write rate of flush and compaction.
-// @rate_bytes_per_sec: desired total write rate in bytes per second.
-// @refill_period_us: token refill interval in micro-second.
+// @rate_bytes_per_sec: this is the only parameter you want to set most of the
+// time. It controls the total write rate of compaction and flush in bytes per
+// second. Currently, RocksDB does not enforce rate limit for anything other
+// than flush and compaction, e.g. write to WAL.
+// @refill_period_us: this controls how often tokens are refilled. For example,
+// when rate_bytes_per_sec is set to 10MB/s and refill_period_us is set to
+// 100ms, then 1MB is refilled every 100ms internally. Larger value can lead to
+// burstier writes while smaller value introduces more CPU overhead.
+// The default should work for most cases.
 // @fairness: RateLimiter accepts high-pri requests and low-pri requests.
-// low-pri request is usually blocked in favor of hi-pri request. To prevent
-// low-pri request from being blocked for too long, it can get processed first
-// by 1/fairness chance.
+// A low-pri request is usually blocked in favor of hi-pri request. Currently,
+// RocksDB assigns low-pri to request from compaciton and high-pri to request
+// from flush. Low-pri requests can get blocked if flush requests come in
+// continuouly. This fairness parameter grants low-pri requests permission by
+// 1/fairness chance even though high-pri requests exist to avoid starvation.
+// You should be good by leaving it at default 10.
 extern RateLimiter* NewRateLimiter(
     int64_t rate_bytes_per_sec,
     int64_t refill_period_us = 100 * 1000,