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 <mrobinson@igalia.com>

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 <https://www.w3.org/TR/cssom-view-1/#dom-htmlelement-offsetparent>:
-/// >
+///
 /// > 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.

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<T: Deref<Target = ComputedValues>>(pub T);
 

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<T> trait from the standard library that can be used
+/// A version of the `Into<T>` 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<T> {
     fn convert(self) -> T;
 }
 
-/// A version of the TryInto<T> trait from the standard library that can be used
+/// A version of the `TryInto<T>` 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.

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)]

components/script/dom/intersectionobserver.rs

@@ -89,7 +89,7 @@ impl IntersectionObserverMethods<crate::DomTypeHolder> 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]`.
     ///
     /// <https://w3c.github.io/IntersectionObserver/#dom-intersectionobserver-thresholds>
     fn Thresholds(&self, _context: JSContext, _retval: MutableHandleValue) {}

components/script/dom/readablestreamdefaultreader.rs

@@ -104,7 +104,7 @@ struct ClosedPromiseRejectionHandler {
 
 impl Callback for ClosedPromiseRejectionHandler {
     /// Continuation of <https://streams.spec.whatwg.org/#readable-stream-default-controller-call-pull-if-needed>
-    /// 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;

components/script/iframe_collection.rs

@@ -109,7 +109,7 @@ impl IFrameCollection {
     }
 
     /// Update the recorded iframe sizes of the contents of layout. Return a
-    /// [`Vec<IFrameSizeMsg`] containing the messages to send to the `Constellation`. A
+    /// [`Vec<IFrameSizeMsg>`] 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,

components/script/messaging.rs

@@ -318,12 +318,13 @@ pub(crate) struct ScriptThreadReceivers {
     #[no_trace]
     pub image_cache_receiver: Receiver<ImageCacheMsg>,
 
-    /// For receiving commands from an optional devtools server. Will be ignored if
+    /// For receiving commands from an optional devtools server. Will be ignored if no such server
-    /// no such server exists.
+    /// exists. When devtools are not active this will be [`crossbeam_channel::never()`].
     #[no_trace]
     pub devtools_server_receiver: Receiver<DevtoolScriptControlMsg>,
 
-    /// 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<Receiver<WebGPUMsg>>,

components/script/script_thread.rs

@@ -287,12 +287,12 @@ pub struct ScriptThread {
     #[no_trace]
     image_cache: Arc<dyn ImageCache>,
 
-    /// 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
+    /// A [`ScriptThreadSenders`] that holds all outgoing sending channels necessary to communicate
-    /// from the [`ScriptThread`].
+    /// 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

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<Value> implementations
+/// Helper for `PartialEq<Value>` implementations
 fn str_vals(nodes: &[DomRoot<Node>]) -> HashSet<String> {
     nodes
         .iter()
@@ -44,7 +44,7 @@ fn str_vals(nodes: &[DomRoot<Node>]) -> HashSet<String> {
         .collect()
 }
 
-/// Helper for PartialEq<Value> implementations
+/// Helper for `PartialEq<Value>` implementations
 fn num_vals(nodes: &[DomRoot<Node>]) -> Vec<f64> {
     nodes
         .iter()

components/shared/embedder/resources.rs

@@ -55,7 +55,7 @@ pub fn sandbox_access_files_dirs() -> Vec<PathBuf> {
 }
 
 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.