From 6e2d3b80b9bc1beca0e75fb93825ad40bde7e55c Mon Sep 17 00:00:00 2001
From: Mark Nelson <mnelson@redhat.com>
Date: Fri, 4 Aug 2017 10:03:05 -0500
Subject: [PATCH] options: update some descriptions and see_also fields.

Signed-off-by: Mark Nelson <mnelson@redhat.com>
---
 src/common/options.cc | 86 +++++++++++++++++++++++++++----------------
 1 file changed, 55 insertions(+), 31 deletions(-)

diff --git a/src/common/options.cc b/src/common/options.cc
index a9f2c6e25ef..5d7bb71a539 100644
--- a/src/common/options.cc
+++ b/src/common/options.cc
@@ -2635,12 +2635,14 @@ std::vector<Option> get_global_options() {
     Option("osd_op_num_threads_per_shard_hdd", Option::TYPE_INT, Option::LEVEL_ADVANCED)
     .set_default(1)
     .set_flag(Option::FLAG_STARTUP)
-    .set_description(""),
+    .set_description("")
+    .add_see_also("osd_op_num_threads_per_shard"),
 
     Option("osd_op_num_threads_per_shard_ssd", Option::TYPE_INT, Option::LEVEL_ADVANCED)
     .set_default(2)
     .set_flag(Option::FLAG_STARTUP)
-    .set_description(""),
+    .set_description("")
+    .add_see_also("osd_op_num_threads_per_shard"),
 
     Option("osd_op_num_shards", Option::TYPE_INT, Option::LEVEL_ADVANCED)
     .set_default(0)
@@ -2650,12 +2652,14 @@ std::vector<Option> get_global_options() {
     Option("osd_op_num_shards_hdd", Option::TYPE_INT, Option::LEVEL_ADVANCED)
     .set_default(5)
     .set_flag(Option::FLAG_STARTUP)
-    .set_description(""),
+    .set_description("")
+    .add_see_also("osd_op_num_shards"),
 
     Option("osd_op_num_shards_ssd", Option::TYPE_INT, Option::LEVEL_ADVANCED)
     .set_default(8)
     .set_flag(Option::FLAG_STARTUP)
-    .set_description(""),
+    .set_description("")
+    .add_see_also("osd_op_num_shards"),
 
     Option("osd_skip_data_digest", Option::TYPE_BOOL, Option::LEVEL_DEV)
     .set_default(false)
@@ -3170,11 +3174,13 @@ std::vector<Option> get_global_options() {
 
     Option("osd_recovery_sleep_ssd", Option::TYPE_FLOAT, Option::LEVEL_ADVANCED)
     .set_default(0)
-    .set_description("Time in seconds to sleep before next recovery or backfill op for SSDs"),
+    .set_description("Time in seconds to sleep before next recovery or backfill op for SSDs")
+    .add_see_also("osd_recovery_sleep"),
 
     Option("osd_recovery_sleep_hybrid", Option::TYPE_FLOAT, Option::LEVEL_ADVANCED)
     .set_default(0.025)
-    .set_description("Time in seconds to sleep before next recovery or backfill op when data is on HDD and journal is on SSD"),
+    .set_description("Time in seconds to sleep before next recovery or backfill op when data is on HDD and journal is on SSD")
+    .add_see_also("osd_recovery_sleep"),
 
     Option("osd_snap_trim_sleep", Option::TYPE_FLOAT, Option::LEVEL_ADVANCED)
     .set_default(0)
@@ -4274,12 +4280,14 @@ std::vector<Option> get_global_options() {
     Option("bluestore_min_alloc_size_hdd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(64_K)
     .set_flag(Option::FLAG_CREATE)
-    .set_description("Default min_alloc_size value for rotational media"),
+    .set_description("Default min_alloc_size value for rotational media")
+    .add_see_also("bluestore_min_alloc_size"),
 
     Option("bluestore_min_alloc_size_ssd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(16_K)
     .set_flag(Option::FLAG_CREATE)
-    .set_description("Default min_alloc_size value for non-rotational (solid state)  media"),
+    .set_description("Default min_alloc_size value for non-rotational (solid state)  media")
+    .add_see_also("bluestore_min_alloc_size"),
 
     Option("bluestore_max_alloc_size", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(0)
@@ -4294,12 +4302,14 @@ std::vector<Option> get_global_options() {
     Option("bluestore_prefer_deferred_size_hdd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(32768)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default bluestore_prefer_deferred_size for rotational media"),
+    .set_description("Default bluestore_prefer_deferred_size for rotational media")
+    .add_see_also("bluestore_prefer_deferred_size"),
 
     Option("bluestore_prefer_deferred_size_ssd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(0)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default bluestore_prefer_deferred_size for non-rotational (solid state) media"),
+    .set_description("Default bluestore_prefer_deferred_size for non-rotational (solid state) media")
+    .add_see_also("bluestore_prefer_deferred_size"),
 
     Option("bluestore_compression_mode", Option::TYPE_STR, Option::LEVEL_ADVANCED)
     .set_default("none")
@@ -4324,12 +4334,14 @@ std::vector<Option> get_global_options() {
     Option("bluestore_compression_min_blob_size_hdd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(128_K)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default value of bluestore_compression_min_blob_size for rotational media"),
+    .set_description("Default value of bluestore_compression_min_blob_size for rotational media")
+    .add_see_also("bluestore_compression_min_blob_size"),
 
     Option("bluestore_compression_min_blob_size_ssd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(8_K)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default value of bluestore_compression_min_blob_size for non-rotational (solid state) media"),
+    .set_description("Default value of bluestore_compression_min_blob_size for non-rotational (solid state) media")
+    .add_see_also("bluestore_compression_min_blob_size"),
 
     Option("bluestore_compression_max_blob_size", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(0)
@@ -4340,12 +4352,14 @@ std::vector<Option> get_global_options() {
     Option("bluestore_compression_max_blob_size_hdd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(512_K)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default value of bluestore_compression_max_blob_size for rotational media"),
+    .set_description("Default value of bluestore_compression_max_blob_size for rotational media")
+    .add_see_also("bluestore_compression_max_blob_size"),
 
     Option("bluestore_compression_max_blob_size_ssd", Option::TYPE_SIZE, Option::LEVEL_ADVANCED)
     .set_default(64_K)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default value of bluestore_compression_max_blob_size for non-rotational (solid state) media"),
+    .set_description("Default value of bluestore_compression_max_blob_size for non-rotational (solid state) media")
+    .add_see_also("bluestore_compression_max_blob_size"),
 
     Option("bluestore_gc_enable_blob_threshold", Option::TYPE_INT, Option::LEVEL_DEV)
     .set_default(0)
@@ -4360,17 +4374,20 @@ std::vector<Option> get_global_options() {
     Option("bluestore_max_blob_size", Option::TYPE_SIZE, Option::LEVEL_DEV)
     .set_default(0)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description(""),
+    .set_description("")
+    .set_long_description("Bluestore blobs are collections of extents (ie on-disk data) originating from one or more objects.  Blobs can be compressed, typically have checksum data, may be overwritten, may be shared (with an extent ref map), or split.  This setting controls the maximum size a blob is allowed to be."),
 
     Option("bluestore_max_blob_size_hdd", Option::TYPE_SIZE, Option::LEVEL_DEV)
     .set_default(512_K)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description(""),
+    .set_description("")
+    .add_see_also("bluestore_max_blob_size"),
 
     Option("bluestore_max_blob_size_ssd", Option::TYPE_SIZE, Option::LEVEL_DEV)
     .set_default(64_K)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description(""),
+    .set_description("")
+    .add_see_also("bluestore_max_blob_size"),
 
     Option("bluestore_compression_required_ratio", Option::TYPE_FLOAT, Option::LEVEL_ADVANCED)
     .set_default(.875)
@@ -4426,11 +4443,13 @@ std::vector<Option> get_global_options() {
 
     Option("bluestore_cache_size_hdd", Option::TYPE_SIZE, Option::LEVEL_DEV)
     .set_default(1_G)
-    .set_description("Default bluestore_cache_size for rotational media"),
+    .set_description("Default bluestore_cache_size for rotational media")
+    .add_see_also("bluestore_cache_size"),
 
     Option("bluestore_cache_size_ssd", Option::TYPE_SIZE, Option::LEVEL_DEV)
     .set_default(3_G)
-    .set_description("Default bluestore_cache_size for non-rotational (solid state) media"),
+    .set_description("Default bluestore_cache_size for non-rotational (solid state) media")
+    .add_see_also("bluestore_cache_size"),
 
     Option("bluestore_cache_meta_ratio", Option::TYPE_FLOAT, Option::LEVEL_DEV)
     .set_default(.4)
@@ -4461,7 +4480,8 @@ std::vector<Option> get_global_options() {
     Option("bluestore_allocator", Option::TYPE_STR, Option::LEVEL_ADVANCED)
     .set_default("bitmap")
     .set_enum_allowed({"bitmap", "stupid"})
-    .set_description("Allocator policy"),
+    .set_description("Allocator policy")
+    .set_long_description("Allocator to use for bluestore.  Stupid should only be used for testing."),
 
     Option("bluestore_freelist_blocks_per_key", Option::TYPE_SIZE, Option::LEVEL_DEV)
     .set_default(128)
@@ -4542,13 +4562,14 @@ std::vector<Option> get_global_options() {
   Option("bluestore_throttle_cost_per_io_hdd", Option::TYPE_UINT, Option::LEVEL_ADVANCED)
     .set_default(670000)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default bluestore_throttle_cost_per_io for rotational media"),
+    .set_description("Default bluestore_throttle_cost_per_io for rotational media")
+    .add_see_also("bluestore_throttle_cost_per_io"),
 
     Option("bluestore_throttle_cost_per_io_ssd", Option::TYPE_UINT, Option::LEVEL_ADVANCED)
     .set_default(4000)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default bluestore_throttle_cost_per_io for non-rotation (solid state) media"),
-
+    .set_description("Default bluestore_throttle_cost_per_io for non-rotation (solid state) media")
+    .add_see_also("bluestore_throttle_cost_per_io"),
 
     Option("bluestore_deferred_batch_ops", Option::TYPE_UINT, Option::LEVEL_ADVANCED)
     .set_default(0)
@@ -4558,12 +4579,14 @@ std::vector<Option> get_global_options() {
     Option("bluestore_deferred_batch_ops_hdd", Option::TYPE_UINT, Option::LEVEL_ADVANCED)
     .set_default(64)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default bluestore_deferred_batch_ops for rotational media"),
+    .set_description("Default bluestore_deferred_batch_ops for rotational media")
+    .add_see_also("bluestore_deferred_batch_ops"),
 
     Option("bluestore_deferred_batch_ops_ssd", Option::TYPE_UINT, Option::LEVEL_ADVANCED)
     .set_default(16)
     .set_flag(Option::FLAG_RUNTIME)
-    .set_description("Default bluestore_deferred_batch_ops for non-rotational (solid state) media"),
+    .set_description("Default bluestore_deferred_batch_ops for non-rotational (solid state) media")
+    .add_see_also("bluestore_deferred_batch_ops"),
 
     Option("bluestore_nid_prealloc", Option::TYPE_INT, Option::LEVEL_DEV)
     .set_default(1024)
@@ -4678,15 +4701,15 @@ std::vector<Option> get_global_options() {
 
     Option("kstore_rocksdb_options", Option::TYPE_STR, Option::LEVEL_ADVANCED)
     .set_default("compression=kNoCompression")
-    .set_description(""),
+    .set_description("Options to pass through when RocksDB is used as the KeyValueDB for kstore."),
 
     Option("kstore_fsck_on_mount", Option::TYPE_BOOL, Option::LEVEL_ADVANCED)
     .set_default(false)
-    .set_description(""),
+    .set_description("Whether or not to run fsck on mount for kstore."),
 
     Option("kstore_fsck_on_mount_deep", Option::TYPE_BOOL, Option::LEVEL_ADVANCED)
     .set_default(true)
-    .set_description(""),
+    .set_description("Whether or not to run deep fsck on mount for kstore"),
 
     Option("kstore_nid_prealloc", Option::TYPE_UINT, Option::LEVEL_ADVANCED)
     .set_default(1024)
@@ -4713,15 +4736,16 @@ std::vector<Option> get_global_options() {
 
     Option("filestore_rocksdb_options", Option::TYPE_STR, Option::LEVEL_DEV)
     .set_default("max_background_jobs=10,compaction_readahead_size=2097152,compression=kNoCompression")
-    .set_description(""),
+    .set_description("Options to pass through when RocksDB is used as the KeyValueDB for filestore."),
 
     Option("filestore_omap_backend", Option::TYPE_STR, Option::LEVEL_DEV)
     .set_default("rocksdb")
-    .set_description(""),
+    .set_enum_allowed({"leveldb", "rocksdb"})
+    .set_description("The KeyValueDB to use for filestore metadata (ie omap)."),
 
     Option("filestore_omap_backend_path", Option::TYPE_STR, Option::LEVEL_DEV)
     .set_default("")
-    .set_description(""),
+    .set_description("The path where the filestore KeyValueDB should store it's database(s)."),
 
     Option("filestore_wbthrottle_enable", Option::TYPE_BOOL, Option::LEVEL_ADVANCED)
     .set_default(true)
-- 
2.39.5