doc(resources): Add documentation to undocumented `embedder_traits::resources::Resource` variants (#33885)

* Document Resource variants and update blocklist url

Signed-off-by: DK Liao <dklassic@gmail.com>

* Update components/shared/embedder/resources.rs

Co-authored-by: Josh Matthews <josh@joshmatthews.net>
Signed-off-by: DK Liao <dklassic@gmail.com>

* Update components/shared/embedder/resources.rs

Co-authored-by: Josh Matthews <josh@joshmatthews.net>
Signed-off-by: DK Liao <dklassic@gmail.com>

* Update components/shared/embedder/resources.rs

Co-authored-by: Josh Matthews <josh@joshmatthews.net>
Signed-off-by: DK Liao <dklassic@gmail.com>

* Update format and reduce length

Signed-off-by: DK Liao <dklassic@gmail.com>

* Slightly changes the line break position

Signed-off-by: DK Liao <dklassic@gmail.com>

---------

Signed-off-by: DK Liao <dklassic@gmail.com>
Co-authored-by: Josh Matthews <josh@joshmatthews.net>

2 files changed, 37 insertions, 1 deletions

diff --git a/components/shared/bluetooth/blocklist.rs b/components/shared/bluetooth/blocklist.rs
index 0435d6f498b..cc839d8f47a 100644
--- a/components/shared/bluetooth/blocklist.rs
+++ b/components/shared/bluetooth/blocklist.rs
@@ -63,7 +63,7 @@ impl BluetoothBlocklist {
     }
 }
 
-// https://webbluetoothcg.github.io/web-bluetooth/#parsing-the-blocklist
+// https://webbluetoothcg.github.io/web-bluetooth/#the-blocklist
 fn parse_blocklist() -> Option<HashMap<String, Blocklist>> {
     // Step 1 missing, currently we parse ./resources/gatt_blocklist.txt.
     let valid_uuid_regex = Regex::new(VALID_UUID_REGEX).unwrap();
diff --git a/components/shared/embedder/resources.rs b/components/shared/embedder/resources.rs
index df27b0fc35c..0dc7d4c65f6 100644
--- a/components/shared/embedder/resources.rs
+++ b/components/shared/embedder/resources.rs
@@ -58,16 +58,41 @@ pub enum Resource {
     /// A json file of [`Preferences`](servo_config::pref_util::Preferences) configuration.
     /// It can be empty but lots of features will be disabled.
     Preferences,
+    /// A list of GATT services that are blocked from being used by web bluetooth.
+    /// The format of the file is a list of UUIDs, one per line, with an optional second word to specify the
+    /// type of blocklist.
+    /// It can be empty but then all GATT services will be allowed.
     BluetoothBlocklist,
+    /// A list of domain names that are considered public suffixes, typically obtained from <https://publicsuffix.org/list/>.
+    /// The Public Suffix List is a cross-vendor initiative to provide an accurate list of domain name suffixes
+    /// that are under the control of a registry. This is used to prevent cookies from being set for top-level
+    /// domains that are not controlled by the same entity as the website.
+    /// It can be empty but all domain names will be considered not public suffixes.
     DomainList,
     /// A preloaded list of HTTP Strict Transport Security. It can be an empty list and
     /// [`HstsList::default()`](net::hsts::HstsList) will be called.
     HstsPreloadList,
+    /// A HTML page to display when [`SslValidation`](net_traits::NetworkError::SslValidation) network error is
+    /// reported.
+    /// The page contains placeholder `${reason}` for the error code and `${bytes}` for the certificate bytes,
+    /// and also `${secret}` for the privileged secret.
+    /// It can be empty but then nothing will be displayed when a certificate error occurs.
     BadCertHTML,
+    /// A HTML page to display when any network error occurs that is not related to SSL validation.
+    /// The message can contain a placeholder `${reason}` for the error code.
+    /// It can be empty but then nothing will be displayed when an internal error occurs.
     NetErrorHTML,
+    /// A CSS file to style the user agent stylesheet.
+    /// It can be empty but then there's simply no user agent stylesheet.
     UserAgentCSS,
+    /// A CSS file to style the Servo browser.
+    /// It can be empty but several features might not work as expected.
     ServoCSS,
+    /// A CSS file to style the presentational hints.
+    /// It can be empty but then presentational hints will not be styled.
     PresentationalHintsCSS,
+    /// A CSS file to style the quirks mode.
+    /// It can be empty but then quirks mode will not be styled.
     QuirksModeCSS,
     /// A placeholder image to display if we couldn't get the requested image.
     ///
@@ -76,9 +101,20 @@ pub enum Resource {
     /// Servo will crash if this is an invalid image. Check `resources/rippy.png` in Servo codebase to see what
     /// a default rippy png should look like.
     RippyPNG,
+    /// A CSS file to style the media controls.
+    /// It can be empty but then media controls will not be styled.
     MediaControlsCSS,
+    /// A JS file to control the media controls.
+    /// It can be empty but then media controls will not work.
     MediaControlsJS,
+    /// A placeholder HTML page to display when the code responsible for rendering a page panics and the original
+    /// page can no longer be displayed.
+    /// The message can contain a placeholder `${details}` for the error details.
+    /// It can be empty but then nothing will be displayed when a crash occurs.
     CrashHTML,
+    /// A HTML page to display when a directory listing is requested.
+    /// The page contains a js function `setData` that will then be used to build the list of directory.
+    /// It can be empty but then nothing will be displayed when a directory listing is requested.
     DirectoryListingHTML,
 }