From 2f32359e8b8bc217213bbe76d5c12969f522c54f Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Thu, 10 Oct 2024 00:34:38 +0700 Subject: [PATCH] Improve docs. (#590) This mainly adds missing backticks and fixes some unmatched backticks. --- communication/src/logging.rs | 4 ++-- communication/src/networking.rs | 8 +++---- timely/src/dataflow/operators/branch.rs | 4 ++-- .../dataflow/operators/core/capture/replay.rs | 4 ++-- timely/src/dataflow/operators/core/probe.rs | 6 ++--- .../src/dataflow/operators/flow_controlled.rs | 4 ++-- timely/src/dataflow/scopes/mod.rs | 2 +- timely/src/logging.rs | 10 ++++---- timely/src/order.rs | 4 ++-- timely/src/progress/change_batch.rs | 4 ++-- timely/src/progress/frontier.rs | 24 +++++++++---------- timely/src/progress/mod.rs | 2 +- timely/src/progress/reachability.rs | 6 ++--- timely/src/progress/timestamp.rs | 4 ++-- timely/src/worker.rs | 6 ++--- 15 files changed, 46 insertions(+), 46 deletions(-) diff --git a/communication/src/logging.rs b/communication/src/logging.rs index 7b0113182f..aadb11e9d5 100644 --- a/communication/src/logging.rs +++ b/communication/src/logging.rs @@ -5,7 +5,7 @@ use serde::{Serialize, Deserialize}; /// Configuration information about a communication thread. #[derive(Debug, PartialEq, Eq, Hash, Clone, Copy, Serialize, Deserialize)] pub struct CommunicationSetup { - /// True when this is a send thread (or the receive thread). + /// `true` when this is a send thread (or the receive thread). pub sender: bool, /// The process id of the thread. pub process: usize, @@ -25,7 +25,7 @@ pub enum CommunicationEvent { /// An observed message. #[derive(Debug, PartialEq, Eq, Hash, Clone, Copy, Serialize, Deserialize)] pub struct MessageEvent { - /// true for send event, false for receive event + /// `true` for send event, `false` for receive event pub is_send: bool, /// associated message header. pub header: crate::networking::MessageHeader, diff --git a/communication/src/networking.rs b/communication/src/networking.rs index 433c2a9110..036e3eef71 100644 --- a/communication/src/networking.rs +++ b/communication/src/networking.rs @@ -87,8 +87,8 @@ impl MessageHeader { /// Creates socket connections from a list of host addresses. /// -/// The item at index i in the resulting vec, is a Some(TcpSocket) to process i, except -/// for item `my_index` which is None (no socket to self). +/// The item at index `i` in the resulting vec, is a `Some(TcpSocket)` to process `i`, except +/// for item `my_index` which is `None` (no socket to self). pub fn create_sockets(addresses: Vec, my_index: usize, noisy: bool) -> Result>> { let hosts1 = Arc::new(addresses); @@ -108,7 +108,7 @@ pub fn create_sockets(addresses: Vec, my_index: usize, noisy: bool) -> R } -/// Result contains connections [0, my_index - 1]. +/// Result contains connections `[0, my_index - 1]`. pub fn start_connections(addresses: Arc>, my_index: usize, noisy: bool) -> Result>> { let results = addresses.iter().take(my_index).enumerate().map(|(index, address)| { loop { @@ -131,7 +131,7 @@ pub fn start_connections(addresses: Arc>, my_index: usize, noisy: bo Ok(results) } -/// Result contains connections [my_index + 1, addresses.len() - 1]. +/// Result contains connections `[my_index + 1, addresses.len() - 1]`. pub fn await_connections(addresses: Arc>, my_index: usize, noisy: bool) -> Result>> { let mut results: Vec<_> = (0..(addresses.len() - my_index - 1)).map(|_| None).collect(); let listener = TcpListener::bind(&addresses[my_index][..])?; diff --git a/timely/src/dataflow/operators/branch.rs b/timely/src/dataflow/operators/branch.rs index 70e087abde..532c5042e0 100644 --- a/timely/src/dataflow/operators/branch.rs +++ b/timely/src/dataflow/operators/branch.rs @@ -9,7 +9,7 @@ use crate::{Container, Data}; pub trait Branch { /// Takes one input stream and splits it into two output streams. /// For each record, the supplied closure is called with a reference to - /// the data and its time. If it returns true, the record will be sent + /// the data and its time. If it returns `true`, the record will be sent /// to the second returned stream, otherwise it will be sent to the first. /// /// If the result of the closure only depends on the time, not the data, @@ -73,7 +73,7 @@ impl Branch for Stream { /// Extension trait for `Stream`. pub trait BranchWhen: Sized { /// Takes one input stream and splits it into two output streams. - /// For each time, the supplied closure is called. If it returns true, + /// For each time, the supplied closure is called. If it returns `true`, /// the records for that will be sent to the second returned stream, otherwise /// they will be sent to the first. /// diff --git a/timely/src/dataflow/operators/core/capture/replay.rs b/timely/src/dataflow/operators/core/capture/replay.rs index e30b640656..1c101f0dd4 100644 --- a/timely/src/dataflow/operators/core/capture/replay.rs +++ b/timely/src/dataflow/operators/core/capture/replay.rs @@ -54,11 +54,11 @@ pub trait Replay : Sized { fn replay_into>(self, scope: &mut S) -> StreamCore { self.replay_core(scope, Some(std::time::Duration::new(0, 0))) } - /// Replays `self` into the provided scope, as a `StreamCore'. + /// Replays `self` into the provided scope, as a `StreamCore`. /// /// The `period` argument allows the specification of a re-activation period, where the operator /// will re-activate itself every so often. The `None` argument instructs the operator not to - /// re-activate itself.us + /// re-activate itself. fn replay_core>(self, scope: &mut S, period: Option) -> StreamCore; } diff --git a/timely/src/dataflow/operators/core/probe.rs b/timely/src/dataflow/operators/core/probe.rs index 592899a22e..b6035ae13b 100644 --- a/timely/src/dataflow/operators/core/probe.rs +++ b/timely/src/dataflow/operators/core/probe.rs @@ -145,11 +145,11 @@ pub struct Handle { } impl Handle { - /// returns true iff the frontier is strictly less than `time`. + /// Returns `true` iff the frontier is strictly less than `time`. #[inline] pub fn less_than(&self, time: &T) -> bool { self.frontier.borrow().less_than(time) } - /// returns true iff the frontier is less than or equal to `time`. + /// Returns `true` iff the frontier is less than or equal to `time`. #[inline] pub fn less_equal(&self, time: &T) -> bool { self.frontier.borrow().less_equal(time) } - /// returns true iff the frontier is empty. + /// Returns `true` iff the frontier is empty. #[inline] pub fn done(&self) -> bool { self.frontier.borrow().is_empty() } /// Allocates a new handle. #[inline] pub fn new() -> Self { Handle { frontier: Rc::new(RefCell::new(MutableAntichain::new())) } } diff --git a/timely/src/dataflow/operators/flow_controlled.rs b/timely/src/dataflow/operators/flow_controlled.rs index 029506a596..c7079500f7 100644 --- a/timely/src/dataflow/operators/flow_controlled.rs +++ b/timely/src/dataflow/operators/flow_controlled.rs @@ -20,8 +20,8 @@ pub struct IteratorSourceInput, I: I } /// Construct a source that repeatedly calls the provided function to ingest input. -/// - The function can return None to signal the end of the input; -/// - otherwise, it should return a `IteratorSourceInput`, where: +/// - The function can return `None` to signal the end of the input; +/// - otherwise, it should return a [`IteratorSourceInput`], where: /// * `lower_bound` is a lower bound on timestamps that can be emitted by this input in the future, /// `Default::default()` can be used if this isn't needed (the source will assume that /// the timestamps in `data` are monotonically increasing and will release capabilities diff --git a/timely/src/dataflow/scopes/mod.rs b/timely/src/dataflow/scopes/mod.rs index 28cc141f78..511bfe492a 100644 --- a/timely/src/dataflow/scopes/mod.rs +++ b/timely/src/dataflow/scopes/mod.rs @@ -25,7 +25,7 @@ impl ScopeParent for crate::worker::Worker { /// The fundamental operations required to add and connect operators in a timely dataflow graph. /// /// Importantly, this is often a *shared* object, backed by a `Rc>` wrapper. Each method -/// takes a shared reference, but can be thought of as first calling .clone() and then calling the +/// takes a shared reference, but can be thought of as first calling `.clone()` and then calling the /// method. Each method does not hold the `RefCell`'s borrow, and should prevent accidental panics. pub trait Scope: ScopeParent { /// A useful name describing the scope. diff --git a/timely/src/logging.rs b/timely/src/logging.rs index 75c7612ffc..df2e038228 100644 --- a/timely/src/logging.rs +++ b/timely/src/logging.rs @@ -182,7 +182,7 @@ pub enum StartStop { #[derive(Serialize, Deserialize, Debug, Clone, Hash, Eq, PartialEq, Ord, PartialOrd)] /// Operator start or stop. pub struct ScheduleEvent { - /// Worker-unique identifier for the operator, linkable to the identifiers in `OperatesEvent`. + /// Worker-unique identifier for the operator, linkable to the identifiers in [`OperatesEvent`]. pub id: usize, /// `Start` if the operator is starting, `Stop` if it is stopping. /// activity is true if it looks like some useful work was performed during this call (data was @@ -200,7 +200,7 @@ impl ScheduleEvent { #[derive(Serialize, Deserialize, Debug, Clone, Hash, Eq, PartialEq, Ord, PartialOrd)] /// Operator shutdown. pub struct ShutdownEvent { - /// Worker-unique identifier for the operator, linkable to the identifiers in `OperatesEvent`. + /// Worker-unique identifier for the operator, linkable to the identifiers in [`OperatesEvent`]. pub id: usize, } @@ -209,21 +209,21 @@ pub struct ShutdownEvent { pub struct ApplicationEvent { /// Unique event type identifier pub id: usize, - /// True when activity begins, false when it stops + /// `true` when activity begins, `false` when it stops pub is_start: bool, } #[derive(Serialize, Deserialize, Debug, Clone, Hash, Eq, PartialEq, Ord, PartialOrd)] /// Application-defined code start or stop pub struct GuardedMessageEvent { - /// True when activity begins, false when it stops + /// `true` when activity begins, `false` when it stops pub is_start: bool, } #[derive(Serialize, Deserialize, Debug, Clone, Hash, Eq, PartialEq, Ord, PartialOrd)] /// Application-defined code start or stop pub struct GuardedProgressEvent { - /// True when activity begins, false when it stops + /// `true` when activity begins, `false` when it stops pub is_start: bool, } diff --git a/timely/src/order.rs b/timely/src/order.rs index b4b0c46cab..cf551d9e9d 100644 --- a/timely/src/order.rs +++ b/timely/src/order.rs @@ -6,11 +6,11 @@ /// of that trait precludes a distinct `Ord` implementation. We need an independent /// trait if we want to have a partially ordered type that can also be sorted. pub trait PartialOrder: PartialEq { - /// Returns true iff one element is strictly less than the other. + /// Returns `true` iff one element is strictly less than the other. fn less_than(&self, other: &Rhs) -> bool { self.less_equal(other) && self != other } - /// Returns true iff one element is less than or equal to the other. + /// Returns `true` iff one element is less than or equal to the other. fn less_equal(&self, other: &Rhs) -> bool; } diff --git a/timely/src/progress/change_batch.rs b/timely/src/progress/change_batch.rs index a78afd7977..9743a75a30 100644 --- a/timely/src/progress/change_batch.rs +++ b/timely/src/progress/change_batch.rs @@ -56,7 +56,7 @@ impl ChangeBatch { } } - /// Returns true if the change batch is not guaranteed compact. + /// Returns `true` if the change batch is not guaranteed compact. pub fn is_dirty(&self) -> bool { self.updates.len() > self.clean } @@ -206,7 +206,7 @@ where self.updates.drain(..) } - /// True iff all keys have value zero. + /// Returns `true` iff all keys have value zero. /// /// This method requires mutable access to `self` because it may need to compact the representation /// to determine if the batch of updates is indeed empty. We could also implement a weaker form of diff --git a/timely/src/progress/frontier.rs b/timely/src/progress/frontier.rs index 82f2bbc8b3..e10a7c7f43 100644 --- a/timely/src/progress/frontier.rs +++ b/timely/src/progress/frontier.rs @@ -24,7 +24,7 @@ pub struct Antichain { impl Antichain { /// Updates the `Antichain` if the element is not greater than or equal to some present element. /// - /// Returns true if element is added to the set + /// Returns `true` if element is added to the set /// /// # Examples /// @@ -48,7 +48,7 @@ impl Antichain { /// Updates the `Antichain` if the element is not greater than or equal to some present element. /// - /// Returns true if element is added to the set + /// Returns `true` if element is added to the set /// /// Accepts a reference to an element, which is cloned when inserting. /// @@ -76,7 +76,7 @@ impl Antichain { /// If the antichain needs updating, it uses the `to_owned` closure to convert the element into /// a `T`. /// - /// Returns true if element is added to the set + /// Returns `true` if element is added to the set /// /// # Examples /// @@ -103,7 +103,7 @@ impl Antichain { self.elements.reserve(additional); } - /// Performs a sequence of insertion and return true iff any insertion does. + /// Performs a sequence of insertion and returns `true` iff any insertion does. /// /// # Examples /// @@ -123,7 +123,7 @@ impl Antichain { added } - /// Returns true if any item in the antichain is strictly less than the argument. + /// Returns `true` if any item in the antichain is strictly less than the argument. /// /// # Examples /// @@ -143,7 +143,7 @@ impl Antichain { self.elements.iter().any(|x| x.less_than(time)) } - /// Returns true if any item in the antichain is less than or equal to the argument. + /// Returns `true` if any item in the antichain is less than or equal to the argument. /// /// # Examples /// @@ -163,7 +163,7 @@ impl Antichain { self.elements.iter().any(|x| x.less_equal(time)) } - /// Returns true if every element of `other` is greater or equal to some element of `self`. + /// Returns `true` if every element of `other` is greater or equal to some element of `self`. #[deprecated(since="0.12.0", note="please use `PartialOrder::less_equal` instead")] #[inline] pub fn dominates(&self, other: &Antichain) -> bool { @@ -455,7 +455,7 @@ impl MutableAntichain { } } - /// Returns true if there are no elements in the `MutableAntichain`. + /// Returns `true` if there are no elements in the `MutableAntichain`. /// /// # Examples /// @@ -470,7 +470,7 @@ impl MutableAntichain { self.frontier.is_empty() } - /// Returns true if any item in the `MutableAntichain` is strictly less than the argument. + /// Returns `true` if any item in the `MutableAntichain` is strictly less than the argument. /// /// # Examples /// @@ -490,7 +490,7 @@ impl MutableAntichain { self.frontier().less_than(time) } - /// Returns true if any item in the `MutableAntichain` is less than or equal to the argument. + /// Returns `true` if any item in the `MutableAntichain` is less than or equal to the argument. /// /// # Examples /// @@ -714,7 +714,7 @@ impl<'a, T: 'a> AntichainRef<'a, T> { impl AntichainRef<'_, T> { - /// Returns true if any item in the `AntichainRef` is strictly less than the argument. + /// Returns `true` if any item in the `AntichainRef` is strictly less than the argument. /// /// # Examples /// @@ -731,7 +731,7 @@ impl AntichainRef<'_, T> { self.iter().any(|x| x.less_than(time)) } - /// Returns true if any item in the `AntichainRef` is less than or equal to the argument. + /// Returns `true` if any item in the `AntichainRef` is less than or equal to the argument. #[inline] /// /// # Examples diff --git a/timely/src/progress/mod.rs b/timely/src/progress/mod.rs index f57108c0d8..ebfb1a7dd3 100644 --- a/timely/src/progress/mod.rs +++ b/timely/src/progress/mod.rs @@ -20,7 +20,7 @@ pub mod subgraph; pub struct Location { /// A scope-local operator identifier. pub node: usize, - /// An operator port identifier.` + /// An operator port identifier. pub port: Port, } diff --git a/timely/src/progress/reachability.rs b/timely/src/progress/reachability.rs index 0380216c8e..9521b31cd7 100644 --- a/timely/src/progress/reachability.rs +++ b/timely/src/progress/reachability.rs @@ -446,12 +446,12 @@ impl PortInformation { } } - /// True if updates at this pointstamp uniquely block progress. + /// Returns `true` if updates at this pointstamp uniquely block progress. /// - /// This method returns true if the currently maintained pointstamp + /// This method returns `true` if the currently maintained pointstamp /// counts are such that zeroing out outstanding updates at *this* /// pointstamp would change the frontiers at this operator. When the - /// method returns false it means that, temporarily at least, there + /// method returns `false` it means that, temporarily at least, there /// are outstanding pointstamp updates that are strictly less than /// this pointstamp. #[inline] diff --git a/timely/src/progress/timestamp.rs b/timely/src/progress/timestamp.rs index 9471d32378..3a7b79eb9e 100644 --- a/timely/src/progress/timestamp.rs +++ b/timely/src/progress/timestamp.rs @@ -45,7 +45,7 @@ pub trait PathSummary : Clone+'static+Eq+PartialOrder+Debug+Default { /// /// It is possible that the two composed paths result in an invalid summary, for example when /// integer additions overflow. If it is correct that all timestamps moved along these paths - /// would also result in overflow and be discarded, `followed_by` can return `None. It is very + /// would also result in overflow and be discarded, `followed_by` can return `None`. It is very /// important that this not be used casually, as this does not prevent the actual movement of /// data. /// @@ -67,7 +67,7 @@ impl PathSummary<()> for () { #[inline] fn followed_by(&self, _other: &()) -> Option<()> { Some(()) } } -/// Implements Timestamp and PathSummary for types with a `checked_add` method. +/// Implements [`Timestamp`] and [`PathSummary`] for types with a `checked_add` method. macro_rules! implement_timestamp_add { ($($index_type:ty,)*) => ( $( diff --git a/timely/src/worker.rs b/timely/src/worker.rs index b0af6363b5..4a5c0145b2 100644 --- a/timely/src/worker.rs +++ b/timely/src/worker.rs @@ -412,7 +412,7 @@ impl Worker { !self.dataflows.borrow().is_empty() } - /// Calls `self.step()` as long as `func` evaluates to true. + /// Calls `self.step()` as long as `func` evaluates to `true`. /// /// This method will continually execute even if there is not work /// for the worker to perform. Consider using the similar method @@ -441,7 +441,7 @@ impl Worker { self.step_or_park_while(Some(Duration::from_secs(0)), func) } - /// Calls `self.step_or_park(duration)` as long as `func` evaluates to true. + /// Calls `self.step_or_park(duration)` as long as `func` evaluates to `true`. /// /// This method may yield whenever there is no work to perform, as performed /// by `Self::step_or_park()`. Please consult the documentation for further @@ -699,7 +699,7 @@ impl Worker { self.dataflows.borrow().keys().cloned().collect() } - /// True if there is at least one dataflow under management. + /// Returns `true` if there is at least one dataflow under management. pub fn has_dataflows(&self) -> bool { !self.dataflows.borrow().is_empty() }