config: Add documentation for the public API. (#43802)

Testing: No code changes, so no testing is required.

Signed-off-by: Mukilan Thiyagarajan <mukilan@igalia.com>

components/config/lib.rs

@@ -2,6 +2,12 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
+//! This crate provides two mechanisms for configuring the behaviour of the Servo engine.
+//!  - The [`opts`] module exposes a set of global flags that are initialized once
+//!    and cannot be changed at runtime.
+//!  - The [`prefs`] module provides a mechanism to get and set global preference
+//!    values that can be changed at runtime.
+
 #![deny(unsafe_code)]
 
 pub mod opts;

components/config/opts.rs

@@ -2,8 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
-//! Configuration options for a single run of the servo application. Created
-//! from command line arguments.
+//! Options are global configuration options that are initialized once and cannot be changed at
+//! runtime.
 
 use std::default::Default;
 use std::path::PathBuf;
@@ -12,15 +12,14 @@ use std::sync::OnceLock;
 
 use serde::{Deserialize, Serialize};
 
-/// Global flags for Servo, currently set on the command line.
+/// The set of global options supported by Servo. The values for these can be configured during
+/// initialization of Servo and cannot be changed later at runtime.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct Opts {
-    /// `None` to disable the time profiler or `Some` to enable it with:
+    /// `None` to disable the time profiler or `Some` to enable it with either:
     ///
     ///  - an interval in seconds to cause it to produce output on that interval.
-    ///    (`i.e. -p 5`).
     ///  - a file path to write profiling info to a TSV file upon Servo's termination.
-    ///    (`i.e. -p out.tsv`).
     pub time_profiling: Option<OutputOptions>,
 
     /// When the profiler is enabled, this is an optional path to dump a self-contained HTML file
@@ -79,10 +78,10 @@ pub struct Opts {
     pub unminify_css: bool,
 }
 
-/// Debug options for Servo, currently set on the command line with -Z
+/// Debug options for Servo.
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct DiagnosticsLogging {
-    /// List all the debug options.
+    /// Print all the debug options supported by Servo to the standard output.
     pub help: bool,
 
     /// Print the DOM after each restyle.
@@ -202,9 +201,9 @@ impl DiagnosticsLogging {
     }
 }
 
+/// The destination for the time profiler reports.
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub enum OutputOptions {
-    /// Database connection config (hostname, name, user, pass)
     FileName(String),
     Stdout(f64),
 }
@@ -241,16 +240,16 @@ static OPTIONS: OnceLock<Opts> = OnceLock::new();
 /// Initialize options.
 ///
 /// Should only be called once at process startup.
-/// Must be called before the first call to [get].
+/// Must be called before the first call to [`get`].
 pub fn initialize_options(opts: Opts) {
     OPTIONS.set(opts).expect("Already initialized");
 }
 
 /// Get the servo options
 ///
-/// If the servo options have not been initialized by calling [initialize_options], then the
-/// options will be initialized to default values. Outside of tests the options should
-/// be explicitly initialized.
+/// If the servo options have not been initialized by calling [`initialize_options`], then the
+/// options will be initialized to default values. Outside of tests the options should be
+/// explicitly initialized.
 #[inline]
 pub fn get() -> &'static Opts {
     // In unit-tests using default options reduces boilerplate.

components/config/pref_util.rs

@@ -5,6 +5,7 @@
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
+/// The types of preference values in Servo.
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub enum PrefValue {
     Float(f64),
@@ -16,6 +17,8 @@ pub enum PrefValue {
 }
 
 impl PrefValue {
+    /// Parse the `input` string as a preference value. Defaults to a `PrefValue::Str` if the input
+    /// cannot be parsed as valid value of one of the other types.
     pub fn from_booleanish_str(input: &str) -> Self {
         match input {
             "false" => PrefValue::Bool(false),

components/config/prefs.rs

@@ -2,6 +2,8 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
+//! Preferences are the global configuration options that can be changed at runtime.
+
 use std::env::consts::ARCH;
 use std::sync::{RwLock, RwLockReadGuard};
 use std::time::Duration;
@@ -13,7 +15,12 @@ pub use crate::pref_util::PrefValue;
 
 static PREFERENCES: RwLock<Preferences> = RwLock::new(Preferences::const_default());
 
+/// A trait to be implemented by components that wish to be notified about runtime changes to the
+/// global preferences for the current process.
 pub trait PreferencesObserver: Send + Sync {
+    /// This method is called when the global preferences have been updated. The argument to the
+    /// method is an array of tuples where the first component is the name of the preference and
+    /// the second component is the new value of the preference.
     fn prefs_changed(&self, _changes: &[(&'static str, PrefValue)]) {}
 }
 
@@ -25,10 +32,13 @@ pub fn get() -> RwLockReadGuard<'static, Preferences> {
     PREFERENCES.read().unwrap()
 }
 
+/// Subscribe to notifications about changes to the global preferences for the current process.
 pub fn add_observer(observer: Box<dyn PreferencesObserver>) {
     OBSERVERS.write().unwrap().push(observer);
 }
 
+/// Update the values of the global preferences for the current process. This also notifies the
+/// observers previously added using [`add_observer`].
 pub fn set(preferences: Preferences) {
     // Map between Stylo preference names and Servo preference names as the This should be
     // kept in sync with components/script/dom/bindings/codegen/run.py which generates the
@@ -72,6 +82,7 @@ macro_rules! pref {
     };
 }
 
+/// The set of global preferences supported by Servo.
 #[derive(Clone, Deserialize, Serialize, ServoPreferences)]
 pub struct Preferences {
     pub fonts_default: String,