From 93ae8d22fce54bdff06bdc96ef089307fcc997ab Mon Sep 17 00:00:00 2001 From: Martin Robinson Date: Sun, 29 Dec 2024 11:37:57 +0100 Subject: [PATCH] Correct a variety of documentation issues (#34786) Fix some warnings in documentation as well as some faulty documentation introduced in #34776. Signed-off-by: Martin Robinson --- components/layout_2020/query.rs | 2 +- components/layout_2020/taffy/stylo_taffy/wrapper.rs | 2 +- components/script/conversions.rs | 4 ++-- components/script/document_collection.rs | 2 +- components/script/dom/intersectionobserver.rs | 2 +- components/script/dom/readablestreamdefaultreader.rs | 2 +- components/script/iframe_collection.rs | 2 +- components/script/messaging.rs | 7 ++++--- components/script/script_thread.rs | 6 +++--- components/script/xpath/eval_value.rs | 4 ++-- components/shared/embedder/resources.rs | 6 +++--- 11 files changed, 20 insertions(+), 19 deletions(-) diff --git a/components/layout_2020/query.rs b/components/layout_2020/query.rs index 599ad7393d7..b2a017bd236 100644 --- a/components/layout_2020/query.rs +++ b/components/layout_2020/query.rs @@ -522,7 +522,7 @@ fn process_offset_parent_query_inner( /// is eligible to be a parent element for offset* queries. /// /// From : -/// > +/// /// > Return the nearest ancestor element of the element for which at least one of the following is /// > true and terminate this algorithm if such an ancestor is found: /// > 1. The computed value of the position property is not static. diff --git a/components/layout_2020/taffy/stylo_taffy/wrapper.rs b/components/layout_2020/taffy/stylo_taffy/wrapper.rs index d7f6c44526c..ec0575121c4 100644 --- a/components/layout_2020/taffy/stylo_taffy/wrapper.rs +++ b/components/layout_2020/taffy/stylo_taffy/wrapper.rs @@ -8,7 +8,7 @@ use style::properties::ComputedValues; use super::convert; -/// A wrapper struct for anything that Deref's to a [`stylo::ComputedValues`], which +/// A wrapper struct for anything that Deref's to a [`ComputedValues`], which /// implements Taffy's layout traits and can used with Taffy's layout algorithms. pub struct TaffyStyloStyle>(pub T); diff --git a/components/script/conversions.rs b/components/script/conversions.rs index 01186119ff5..c9cd43f5e58 100644 --- a/components/script/conversions.rs +++ b/components/script/conversions.rs @@ -2,7 +2,7 @@ * 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/. */ -/// A version of the Into trait from the standard library that can be used +/// A version of the `Into` trait from the standard library that can be used /// to convert between two types that are not defined in the script crate. /// This is intended to be used on dict/enum types generated from WebIDL once /// those types are moved out of the script crate. @@ -10,7 +10,7 @@ pub trait Convert { fn convert(self) -> T; } -/// A version of the TryInto trait from the standard library that can be used +/// A version of the `TryInto` trait from the standard library that can be used /// to convert between two types that are not defined in the script crate. /// This is intended to be used on dict/enum types generated from WebIDL once /// those types are moved out of the script crate. diff --git a/components/script/document_collection.rs b/components/script/document_collection.rs index d9c28f6b7db..778fef202ac 100644 --- a/components/script/document_collection.rs +++ b/components/script/document_collection.rs @@ -14,7 +14,7 @@ use crate::dom::globalscope::GlobalScope; use crate::dom::htmliframeelement::HTMLIFrameElement; use crate::dom::window::Window; -/// The collection of all [`Document`]s managed by the [`crate::script_thread::SriptThread`]. +/// The collection of all [`Document`]s managed by the [`crate::script_thread::ScriptThread`]. /// This is stored as a mapping of [`PipelineId`] to [`Document`], but for updating the /// rendering, [`Document`]s should be processed in order via [`Self::documents_in_order`]. #[derive(JSTraceable)] diff --git a/components/script/dom/intersectionobserver.rs b/components/script/dom/intersectionobserver.rs index e6d2033e808..fe70429d389 100644 --- a/components/script/dom/intersectionobserver.rs +++ b/components/script/dom/intersectionobserver.rs @@ -89,7 +89,7 @@ impl IntersectionObserverMethods for IntersectionObserver /// > is a ratio of intersection area to bounding box area of an observed target. /// > Notifications for a target are generated when any of the thresholds are crossed /// > for that target. If no options.threshold was provided to the IntersectionObserver - /// > constructor, or the sequence is empty, the value of this attribute will be [0]. + /// > constructor, or the sequence is empty, the value of this attribute will be `[0]`. /// /// fn Thresholds(&self, _context: JSContext, _retval: MutableHandleValue) {} diff --git a/components/script/dom/readablestreamdefaultreader.rs b/components/script/dom/readablestreamdefaultreader.rs index 0508c363ac9..33c545258c2 100644 --- a/components/script/dom/readablestreamdefaultreader.rs +++ b/components/script/dom/readablestreamdefaultreader.rs @@ -104,7 +104,7 @@ struct ClosedPromiseRejectionHandler { impl Callback for ClosedPromiseRejectionHandler { /// Continuation of - /// Upon rejection of reader.[[closedPromise]] with reason r, + /// Upon rejection of `reader.closedPromise` with reason `r``, fn callback(&self, _cx: SafeJSContext, v: SafeHandleValue, _realm: InRealm, _can_gc: CanGc) { let branch_1_controller = &self.branch_1_controller; let branch_2_controller = &self.branch_2_controller; diff --git a/components/script/iframe_collection.rs b/components/script/iframe_collection.rs index 08e1b326ced..d489a4355e7 100644 --- a/components/script/iframe_collection.rs +++ b/components/script/iframe_collection.rs @@ -109,7 +109,7 @@ impl IFrameCollection { } /// Update the recorded iframe sizes of the contents of layout. Return a - /// [`Vec`] containing the messages to send to the `Constellation`. A /// message is only sent when the size actually changes. pub(crate) fn handle_new_iframe_sizes_after_layout( &mut self, diff --git a/components/script/messaging.rs b/components/script/messaging.rs index f077f969b19..76bd536b18c 100644 --- a/components/script/messaging.rs +++ b/components/script/messaging.rs @@ -318,12 +318,13 @@ pub(crate) struct ScriptThreadReceivers { #[no_trace] pub image_cache_receiver: Receiver, - /// For receiving commands from an optional devtools server. Will be ignored if - /// no such server exists. + /// For receiving commands from an optional devtools server. Will be ignored if no such server + /// exists. When devtools are not active this will be [`crossbeam_channel::never()`]. #[no_trace] pub devtools_server_receiver: Receiver, - /// Receiver to receive commands from optional WebGPU server. + /// Receiver to receive commands from optional WebGPU server. When there is no active + /// WebGPU context, this will be [`crossbeam_channel::never()`]. #[no_trace] #[cfg(feature = "webgpu")] pub webgpu_receiver: RefCell>, diff --git a/components/script/script_thread.rs b/components/script/script_thread.rs index 99459e0a7d9..9789ad9f2d5 100644 --- a/components/script/script_thread.rs +++ b/components/script/script_thread.rs @@ -287,12 +287,12 @@ pub struct ScriptThread { #[no_trace] image_cache: Arc, - /// A [`ScriptThreadReceivers`] holding all of the incoming [`Receiver`]s for messages + /// A [`ScriptThreadReceivers`] holding all of the incoming `Receiver`s for messages /// to this [`ScriptThread`]. receivers: ScriptThreadReceivers, - /// A [`ScriptThreadMessaging`] that holds all data necessary to communicate to and - /// from the [`ScriptThread`]. + /// A [`ScriptThreadSenders`] that holds all outgoing sending channels necessary to communicate + /// to other parts of Servo. senders: ScriptThreadSenders, /// A handle to the resource thread. This is an `Arc` to avoid running out of file descriptors if diff --git a/components/script/xpath/eval_value.rs b/components/script/xpath/eval_value.rs index de3f0d9d075..ef0bfe2c4fe 100644 --- a/components/script/xpath/eval_value.rs +++ b/components/script/xpath/eval_value.rs @@ -36,7 +36,7 @@ pub fn str_to_num(s: &str) -> f64 { s.trim().parse().unwrap_or(f64::NAN) } -/// Helper for PartialEq implementations +/// Helper for `PartialEq` implementations fn str_vals(nodes: &[DomRoot]) -> HashSet { nodes .iter() @@ -44,7 +44,7 @@ fn str_vals(nodes: &[DomRoot]) -> HashSet { .collect() } -/// Helper for PartialEq implementations +/// Helper for `PartialEq` implementations fn num_vals(nodes: &[DomRoot]) -> Vec { nodes .iter() diff --git a/components/shared/embedder/resources.rs b/components/shared/embedder/resources.rs index a518061daf7..9fdb8548135 100644 --- a/components/shared/embedder/resources.rs +++ b/components/shared/embedder/resources.rs @@ -55,7 +55,7 @@ pub fn sandbox_access_files_dirs() -> Vec { } pub enum Resource { - /// A json file of [`Preferences`](servo_config::pref_util::Preferences) configuration. + /// A json file of `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. @@ -70,9 +70,9 @@ pub enum Resource { /// 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. + /// `HstsList::default()` will be called. HstsPreloadList, - /// A HTML page to display when [`SslValidation`](net_traits::NetworkError::SslValidation) network error is + /// A HTML page to display when `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.