Merge #2839

2839: Update internal CLI documentation r=curquiza a=jeertmans

# Pull Request

## Related issue
Fixes #2810

## What does this PR do?
- Make internal CLI documentation match the online one

## Remarks
- Scope is limited to `meilisearch/meilisearch-http/src/option.rs`, not the flattened structs: should I also take care of them?
- Could not find online docs for `enable_metrics_route`
- Max column width wrapping was done by hand, so may not be perfect
- I removed the links from the internal doc: should I put them back?

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?


Co-authored-by: Jérome Eertmans <jeertmans@icloud.com>

meilisearch-http/src/option.rs

@@ -66,98 +66,98 @@ const DEFAULT_LOG_LEVEL: &str = "INFO";
 #[clap(version)]
 #[serde(rename_all = "snake_case", deny_unknown_fields)]
 pub struct Opt {
-    /// The destination where the database must be created.
+    /// Designates the location where database files will be created and retrieved.
     #[clap(long, env = MEILI_DB_PATH, default_value_os_t = default_db_path())]
     #[serde(default = "default_db_path")]
     pub db_path: PathBuf,
 
-    /// The address on which the http server will listen.
+    /// Sets the HTTP address and port Meilisearch will use.
     #[clap(long, env = MEILI_HTTP_ADDR, default_value_t = default_http_addr())]
     #[serde(default = "default_http_addr")]
     pub http_addr: String,
 
-    /// Sets the instance's master key, automatically protecting all routes except GET /health
+    /// Sets the instance's master key, automatically protecting all routes except `GET /health`.
     #[serde(skip_serializing)]
     #[clap(long, env = MEILI_MASTER_KEY)]
     pub master_key: Option<String>,
 
-    /// This environment variable must be set to `production` if you are running in production.
+    /// Configures the instance's environment. Value must be either `production` or `development`.
-    /// More logs wiil be displayed if the server is running in development mode. Setting the master
-    /// key is optional; hence no security on the updates routes. This
-    /// is useful to debug when integrating the engine with another service
     #[clap(long, env = MEILI_ENV, default_value_t = default_env(), possible_values = &POSSIBLE_ENV)]
     #[serde(default = "default_env")]
     pub env: String,
 
-    /// Do not send analytics to Meili.
+    /// Deactivates Meilisearch's built-in telemetry when provided.
+    ///
+    /// Meilisearch automatically collects data from all instances that do not opt out using this flag.
+    /// All gathered data is used solely for the purpose of improving Meilisearch, and can be deleted
+    /// at any time.
     #[cfg(all(not(debug_assertions), feature = "analytics"))]
     #[serde(skip_serializing, default)] // we can't send true
     #[clap(long, env = MEILI_NO_ANALYTICS)]
     pub no_analytics: bool,
 
-    /// The maximum size, in bytes, of the main LMDB database directory
+    /// Sets the maximum size of the index. Value must be given in bytes or explicitly stating a base unit (for instance: 107374182400, '107.7Gb', or '107374 Mb').
     #[clap(long, env = MEILI_MAX_INDEX_SIZE, default_value_t = default_max_index_size())]
     #[serde(default = "default_max_index_size")]
     pub max_index_size: Byte,
 
-    /// The maximum size, in bytes, of the update LMDB database directory
+    /// Sets the maximum size of the task database. Value must be given in bytes or explicitly stating a
+    /// base unit (for instance: 107374182400, '107.7Gb', or '107374 Mb').
     #[clap(long, env = MEILI_MAX_TASK_DB_SIZE, default_value_t = default_max_task_db_size())]
     #[serde(default = "default_max_task_db_size")]
     pub max_task_db_size: Byte,
 
-    /// The maximum size, in bytes, of accepted JSON payloads
+    /// Sets the maximum size of accepted payloads. Value must be given in bytes or explicitly stating a
+    /// base unit (for instance: 107374182400, '107.7Gb', or '107374 Mb').
     #[clap(long, env = MEILI_HTTP_PAYLOAD_SIZE_LIMIT, default_value_t = default_http_payload_size_limit())]
     #[serde(default = "default_http_payload_size_limit")]
     pub http_payload_size_limit: Byte,
 
-    /// Read server certificates from CERTFILE.
+    /// Sets the server's SSL certificates.
-    /// This should contain PEM-format certificates
-    /// in the right order (the first certificate should
-    /// certify KEYFILE, the last should be a root CA).
     #[serde(skip_serializing)]
     #[clap(long, env = MEILI_SSL_CERT_PATH, parse(from_os_str))]
     pub ssl_cert_path: Option<PathBuf>,
 
-    /// Read the private key from KEYFILE.  This should be an RSA
+    /// Sets the server's SSL key files.
-    /// private key or PKCS8-encoded private key, in PEM format.
     #[serde(skip_serializing)]
     #[clap(long, env = MEILI_SSL_KEY_PATH, parse(from_os_str))]
     pub ssl_key_path: Option<PathBuf>,
 
-    /// Enable client authentication, and accept certificates
+    /// Enables client authentication in the specified path.
-    /// signed by those roots provided in CERTFILE.
     #[serde(skip_serializing)]
     #[clap(long, env = MEILI_SSL_AUTH_PATH, parse(from_os_str))]
     pub ssl_auth_path: Option<PathBuf>,
 
-    /// Read DER-encoded OCSP response from OCSPFILE and staple to certificate.
+    /// Sets the server's OCSP file. *Optional*
-    /// Optional
+    ///
+    /// Reads DER-encoded OCSP response from OCSPFILE and staple to certificate.
     #[serde(skip_serializing)]
     #[clap(long, env = MEILI_SSL_OCSP_PATH, parse(from_os_str))]
     pub ssl_ocsp_path: Option<PathBuf>,
 
-    /// Send a fatal alert if the client does not complete client authentication.
+    /// Makes SSL authentication mandatory.
     #[serde(skip_serializing, default)]
     #[clap(long, env = MEILI_SSL_REQUIRE_AUTH)]
     pub ssl_require_auth: bool,
 
-    /// SSL support session resumption
+    /// Activates SSL session resumption.
     #[serde(skip_serializing, default)]
     #[clap(long, env = MEILI_SSL_RESUMPTION)]
     pub ssl_resumption: bool,
 
-    /// SSL support tickets.
+    /// Activates SSL tickets.
     #[serde(skip_serializing, default)]
     #[clap(long, env = MEILI_SSL_TICKETS)]
     pub ssl_tickets: bool,
 
-    /// Defines the path of the snapshot file to import.
+    /// Launches Meilisearch after importing a previously-generated snapshot at the given filepath.
-    /// This option will, by default, stop the process if a database already exists, or if no snapshot exists at
-    /// the given path. If this option is not specified, no snapshot is imported.
     #[clap(long, env = MEILI_IMPORT_SNAPSHOT)]
     pub import_snapshot: Option<PathBuf>,
 
-    /// The engine will ignore a missing snapshot and not return an error in such a case.
+    /// Prevents a Meilisearch instance from throwing an error when `--import-snapshot`
+    /// does not point to a valid snapshot file.
+    ///
+    /// This command will throw an error if `--import-snapshot` is not defined.
     #[clap(
         long,
         env = MEILI_IGNORE_MISSING_SNAPSHOT,
@@ -166,7 +166,11 @@ pub struct Opt {
     #[serde(default)]
     pub ignore_missing_snapshot: bool,
 
-    /// The engine will skip snapshot importation and not return an error in such case.
+    /// Prevents a Meilisearch instance with an existing database from throwing an
+    /// error when using `--import-snapshot`. Instead, the snapshot will be ignored
+    /// and Meilisearch will launch using the existing database.
+    ///
+    /// This command will throw an error if `--import-snapshot` is not defined.
     #[clap(
         long,
         env = MEILI_IGNORE_SNAPSHOT_IF_DB_EXISTS,
@@ -175,42 +179,51 @@ pub struct Opt {
     #[serde(default)]
     pub ignore_snapshot_if_db_exists: bool,
 
-    /// Defines the directory path where Meilisearch will create a snapshot each snapshot-interval-sec.
+    /// Sets the directory where Meilisearch will store snapshots.
     #[clap(long, env = MEILI_SNAPSHOT_DIR, default_value_os_t = default_snapshot_dir())]
     #[serde(default = "default_snapshot_dir")]
     pub snapshot_dir: PathBuf,
 
-    /// Activate snapshot scheduling.
+    /// Activates scheduled snapshots when provided. Snapshots are disabled by default.
     #[clap(long, env = MEILI_SCHEDULE_SNAPSHOT)]
     #[serde(default)]
     pub schedule_snapshot: bool,
 
-    /// Defines time interval, in seconds, between each snapshot creation.
+    /// Defines the interval between each snapshot. Value must be given in seconds.
     #[clap(long, env = MEILI_SNAPSHOT_INTERVAL_SEC, default_value_t = default_snapshot_interval_sec())]
     #[serde(default = "default_snapshot_interval_sec")]
-    // 24h
     pub snapshot_interval_sec: u64,
 
-    /// Import a dump from the specified path, must be a `.dump` file.
+    /// Imports the dump file located at the specified path. Path must point to a `.dump` file.
+    /// If a database already exists, Meilisearch will throw an error and abort launch.
     #[clap(long, env = MEILI_IMPORT_DUMP, conflicts_with = "import-snapshot")]
     pub import_dump: Option<PathBuf>,
 
-    /// If the dump doesn't exist, load or create the database specified by `db-path` instead.
+    /// Prevents Meilisearch from throwing an error when `--import-dump` does not point to
+    /// a valid dump file. Instead, Meilisearch will start normally without importing any dump.
+    ///
+    /// This option will trigger an error if `--import-dump` is not defined.
     #[clap(long, env = MEILI_IGNORE_MISSING_DUMP, requires = "import-dump")]
     #[serde(default)]
     pub ignore_missing_dump: bool,
 
-    /// Ignore the dump if a database already exists, and load that database instead.
+    /// Prevents a Meilisearch instance with an existing database from throwing an error
+    /// when using `--import-dump`. Instead, the dump will be ignored and Meilisearch will
+    /// launch using the existing database.
+    ///
+    /// This option will trigger an error if `--import-dump` is not defined.
     #[clap(long, env = MEILI_IGNORE_DUMP_IF_DB_EXISTS, requires = "import-dump")]
     #[serde(default)]
     pub ignore_dump_if_db_exists: bool,
 
-    /// Folder where dumps are created when the dump route is called.
+    /// Sets the directory where Meilisearch will create dump files.
     #[clap(long, env = MEILI_DUMPS_DIR, default_value_os_t = default_dumps_dir())]
     #[serde(default = "default_dumps_dir")]
     pub dumps_dir: PathBuf,
 
-    /// Set the log level. # Possible values: [ERROR, WARN, INFO, DEBUG, TRACE]
+    /// Defines how much detail should be present in Meilisearch's logs.
+    ///
+    /// Meilisearch currently supports five log levels, listed in order of increasing verbosity: ERROR, WARN, INFO, DEBUG, TRACE.
     #[clap(long, env = MEILI_LOG_LEVEL, default_value_t = default_log_level())]
     #[serde(default = "default_log_level")]
     pub log_level: String,
@@ -229,7 +242,7 @@ pub struct Opt {
     #[clap(flatten)]
     pub scheduler_options: SchedulerConfig,
 
-    /// The path to a configuration file that should be used to setup the engine.
+    /// Set the path to a configuration file that should be used to setup the engine.
     /// Format must be TOML.
     #[serde(skip_serializing)]
     #[clap(long)]

meilisearch-lib/src/options.rs

@@ -17,7 +17,7 @@ const DEFAULT_LOG_EVERY_N: usize = 100000;
 #[derive(Debug, Clone, Parser, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case", deny_unknown_fields)]
 pub struct IndexerOpts {
-    /// The amount of documents to skip before printing
+    /// Sets the amount of documents to skip before printing
     /// a log regarding the indexing advancement.
     #[serde(skip_serializing, default = "default_log_every_n")]
     #[clap(long, default_value_t = default_log_every_n(), hide = true)] // 100k
@@ -28,20 +28,15 @@ pub struct IndexerOpts {
     #[clap(long, hide = true)]
     pub max_nb_chunks: Option<usize>,
 
-    /// The maximum amount of memory the indexer will use.
+    /// Sets the maximum amount of RAM Meilisearch can use when indexing. By default, Meilisearch
-    ///
+    /// uses no more than two thirds of available memory.
-    /// In case the engine is unable to retrieve the available memory the engine will
-    /// try to use the memory it needs but without real limit, this can lead to
-    /// Out-Of-Memory issues and it is recommended to specify the amount of memory to use.
     #[clap(long, env = MEILI_MAX_INDEXING_MEMORY, default_value_t)]
     #[serde(default)]
     pub max_indexing_memory: MaxMemory,
 
-    /// The maximum number of threads the indexer will use.
+    /// Sets the maximum number of threads Meilisearch can use during indexation. By default, the
-    /// If the number set is higher than the real number of cores available in the machine,
+    /// indexer avoids using more than half of a machine's total processing units. This ensures
-    /// it will use the maximum number of available cores.
+    /// Meilisearch is always ready to perform searches, even while you are updating an index.
-    ///
-    /// It defaults to half of the available threads.
     #[clap(long, env = MEILI_MAX_INDEXING_THREADS, default_value_t)]
     #[serde(default)]
     pub max_indexing_threads: MaxThreads,
@@ -50,8 +45,7 @@ pub struct IndexerOpts {
 #[derive(Debug, Clone, Parser, Default, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case", deny_unknown_fields)]
 pub struct SchedulerConfig {
-    /// The engine will disable task auto-batching,
+    /// Deactivates auto-batching when provided.
-    /// and will sequencialy compute each task one by one.
     #[clap(long, env = DISABLE_AUTO_BATCHING)]
     #[serde(default)]
     pub disable_auto_batching: bool,