docs: cleanup doc comments for clippy latest (#1428)

hydro_deploy/core/src/localhost/launched_binary.rs

@@ -76,7 +76,7 @@ impl LaunchedLocalhostBinary {
         );
         let (_, stderr_receivers) = prioritized_broadcast(
             FuturesBufReader::new(child.stderr.take().unwrap()).lines(),
-            move |s| ProgressTracker::println(&format!("[{id} stderr] {s}")),
+            move |s| ProgressTracker::println(format!("[{id} stderr] {s}")),
         );
 
         Self {
@@ -191,7 +191,7 @@ impl LaunchedBinary for LaunchedLocalhostBinary {
                     async move {
                         // Log stderr.
                         while let Ok(Some(s)) = stderr_lines.next_line().await {
-                            ProgressTracker::println(&format!("[perf script stderr] {s}"));
+                            ProgressTracker::println(format!("[perf script stderr] {s}"));
                         }
                         Result::<_>::Ok(())
                     },

hydro_deploy/core/src/localhost/mod.rs

@@ -159,9 +159,9 @@ impl LaunchedHost for LaunchedLocalhost {
         let mut command = if let Some(tracing) = tracing.as_ref() {
             if cfg!(target_os = "macos") || cfg!(target_family = "windows") {
                 // dtrace
-                ProgressTracker::println(&format!(
-                    "[{id} tracing] Profiling binary with `dtrace`.",
-                ));
+                ProgressTracker::println(
+                    format!("[{id} tracing] Profiling binary with `dtrace`.",),
+                );
                 let dtrace_outfile = tracing.dtrace_outfile.as_ref().ok_or_else(|| {
                     anyhow!(
                         "`{}` must be set for `dtrace` on localhost.",
@@ -215,7 +215,7 @@ impl LaunchedHost for LaunchedLocalhost {
             // }
             else if cfg!(target_family = "unix") {
                 // perf
-                ProgressTracker::println(&format!("[{} tracing] Tracing binary with `perf`.", id));
+                ProgressTracker::println(format!("[{} tracing] Tracing binary with `perf`.", id));
                 let perf_outfile = tracing.perf_raw_outfile.as_ref().ok_or_else(|| {
                     anyhow!(
                         "`{}` must be set for `perf` on localhost.",
@@ -257,7 +257,7 @@ impl LaunchedHost for LaunchedLocalhost {
         #[cfg(not(target_family = "unix"))]
         command.kill_on_drop(true);
 
-        ProgressTracker::println(&format!("[{}] running command: `{:?}`", id, command));
+        ProgressTracker::println(format!("[{}] running command: `{:?}`", id, command));
 
         let child = command
             .spawn()

hydroflow/src/util/mod.rs

@@ -177,6 +177,7 @@ pub async fn bind_udp_lines(addr: SocketAddr) -> (UdpLinesSink, UdpLinesStream,
 }
 
 /// Returns a newline-delimited bytes `Sender`, `Receiver`, and `SocketAddr` bound to the given address.
+///
 /// The input `addr` may have a port of `0`, the returned `SocketAddr` will be the address of the newly bound endpoint.
 /// The inbound connections can be used in full duplex mode. When a `(T, SocketAddr)` pair is fed to the `Sender`
 /// returned by this function, the `SocketAddr` will be looked up against the currently existing connections.
@@ -208,7 +209,9 @@ pub async fn bind_tcp_lines(
         .unwrap()
 }
 
-/// This is inverse of bind_tcp_bytes. `(Bytes, SocketAddr)` pairs fed to the returned `Sender` will initiate new tcp connections to the specified `SocketAddr`.
+/// The inverse of [`bind_tcp_bytes`].
+///
+/// `(Bytes, SocketAddr)` pairs fed to the returned `Sender` will initiate new tcp connections to the specified `SocketAddr`.
 /// These connections will be cached and reused, so that there will only be one connection per destination endpoint. When the endpoint sends data back it will be available via the returned `Receiver`
 #[cfg(not(target_arch = "wasm32"))]
 pub fn connect_tcp_bytes() -> (
@@ -239,9 +242,13 @@ where
     slice.sort_unstable_by(|a, b| f(a).cmp(f(b)))
 }
 
-/// When a child process is spawned often you want to wait until the child process is ready before moving on.
-/// One way to do that synchronization is by waiting for the child process to output something and match regex against that output.
-/// For example, you could wait until the child process outputs "Client live!" which would indicate that it is ready to receive input now on stdin.
+/// Waits for a specific process output before returning.
+///
+/// When a child process is spawned often you want to wait until the child process is ready before
+/// moving on. One way to do that synchronization is by waiting for the child process to output
+/// something and match regex against that output. For example, you could wait until the child
+/// process outputs "Client live!" which would indicate that it is ready to receive input now on
+/// stdin.
 pub fn wait_for_process_output(
     output_so_far: &mut String,
     output: &mut ChildStdout,
@@ -264,8 +271,10 @@ pub fn wait_for_process_output(
     }
 }
 
-/// When a `Child` is dropped normally nothing happens but in unit tests you usually want to terminate
-/// the child and wait for it to terminate. `DroppableChild` does that for us.
+/// Terminates the inner [`Child`] process when dropped.
+///
+/// When a `Child` is dropped normally nothing happens but in unit tests you usually want to
+/// terminate the child and wait for it to terminate. `DroppableChild` does that for us.
 pub struct DroppableChild(Child);
 
 impl Drop for DroppableChild {
@@ -279,9 +288,12 @@ impl Drop for DroppableChild {
     }
 }
 
-/// rust examples are meant to be run by people and have a natural interface for that. This makes unit testing them cumbersome.
-/// This function wraps calling cargo run and piping the stdin/stdout of the example to easy to handle returned objects.
-/// The function also returns a `DroppableChild` which will ensure that the child processes will be cleaned up appropriately.
+/// Run a rust example as a test.
+///
+/// Rust examples are meant to be run by people and have a natural interface for that. This makes
+/// unit testing them cumbersome. This function wraps calling cargo run and piping the stdin/stdout
+/// of the example to easy to handle returned objects. The function also returns a `DroppableChild`
+/// which will ensure that the child processes will be cleaned up appropriately.
 pub fn run_cargo_example(test_name: &str, args: &str) -> (DroppableChild, ChildStdin, ChildStdout) {
     let mut server = if args.is_empty() {
         std::process::Command::new("cargo")
@@ -309,19 +321,21 @@ pub fn run_cargo_example(test_name: &str, args: &str) -> (DroppableChild, ChildS
     (DroppableChild(server), stdin, stdout)
 }
 
-/// Returns an [`Stream`] that emits `n` items at a time from `iter` at a time, yielding in-between.
+/// Converts an iterator into a stream that emits `n` items at a time, yielding between each batch.
+///
 /// This is useful for breaking up a large iterator across several ticks: `source_iter(...)` always
 /// releases all items in the first tick. However using `iter_batches_stream` with `source_stream(...)`
 /// will cause `n` items to be released each tick. (Although more than that may be emitted if there
 /// are loops in the stratum).
 pub fn iter_batches_stream<I>(
-    mut iter: I,
+    iter: I,
     n: usize,
 ) -> futures::stream::PollFn<impl FnMut(&mut Context<'_>) -> Poll<Option<I::Item>>>
 where
-    I: Iterator + Unpin,
+    I: IntoIterator + Unpin,
 {
     let mut count = 0;
+    let mut iter = iter.into_iter();
     futures::stream::poll_fn(move |ctx| {
         count += 1;
         if n < count {

hydroflow/src/util/monotonic_map.rs

@@ -2,10 +2,12 @@
 
 use super::clear::Clear;
 
-/// A map-like interface which in reality only stores one value at a time. The keys must be
-/// monotonically increasing (i.e. timestamps). For Hydroflow, this allows state to be stored which
-/// resets each tick by using the tick counter as the key. In the generic `Map` case it can be
-/// swapped out for a true map to allow processing of multiple ticks of data at once.
+/// A map-like interface which in reality only stores one value at a time.
+///
+/// The keys must be monotonically increasing (i.e. timestamps). For Hydroflow, this allows state
+/// to be stored which resets each tick by using the tick counter as the key. In the generic `Map`
+/// case it can be swapped out for a true map to allow processing of multiple ticks of data at
+/// once.
 #[derive(Clone, Debug)]
 pub struct MonotonicMap<K, V>
 where

hydroflow/src/util/tcp.rs

@@ -138,8 +138,11 @@ pub async fn bind_tcp<T: 'static, Codec: 'static + Clone + Decoder + Encoder<T>>
     Ok((tx_egress, rx_ingress, bound_endpoint))
 }
 
-/// This is the inverse of bind_tcp, when messages enqueued into the returned sender, tcp sockets will be created and connected as necessary to send out the requests.
-/// As the responses come back, they will be forwarded to the returned receiver.
+/// The inverse of [`bind_tcp`].
+///
+/// When messages enqueued into the returned sender, tcp sockets will be created and connected as
+/// necessary to send out the requests. As the responses come back, they will be forwarded to the
+/// returned receiver.
 pub fn connect_tcp<T: 'static, Codec: 'static + Clone + Decoder + Encoder<T>>(
     codec: Codec,
 ) -> (TcpFramedSink<T>, TcpFramedStream<Codec>) {

hydroflow/src/util/udp.rs

@@ -13,9 +13,8 @@ use tokio_util::udp::UdpFramed;
 pub type UdpFramedSink<Codec, Item> = SplitSink<UdpFramed<Codec>, (Item, SocketAddr)>;
 /// A framed UDP `Stream` (receiving).
 pub type UdpFramedStream<Codec> = SplitStream<UdpFramed<Codec>>;
-/// Helper creates a UDP `Stream` and `Sink` from the given socket, using the given `Codec` to
-/// handle delineation between inputs/outputs. Also returns the bound UdpSocket, which will be
-/// different than the input UdpSocket if the input socket was set to port 0.
+/// Returns a UDP `Stream`, `Sink`, and address for the given socket, using the given `Codec` to
+/// handle delineation between inputs/outputs.
 pub fn udp_framed<Codec, Item>(
     socket: UdpSocket,
     codec: Codec,

hydroflow_lang/src/graph/hydroflow_graph.rs

@@ -25,9 +25,10 @@ use crate::diagnostic::{Diagnostic, Level};
 use crate::pretty_span::{PrettyRowCol, PrettySpan};
 use crate::process_singletons;
 
-/// A graph representing a Hydroflow dataflow graph (with or without subgraph partitioning,
-/// stratification, and handoff insertion). This is a "meta" graph used for generating Rust source
-/// code in macros from Hydroflow surface sytnax.
+/// An abstract "meta graph" representation of a Hydroflow graph.
+///
+/// Can be with or without subgraph partitioning, stratification, and handoff insertion. This is
+/// the meta graph used for generating Rust source code in macros from Hydroflow surface sytnax.
 ///
 /// This struct has a lot of methods for manipulating the graph, vaguely grouped together in
 /// separate `impl` blocks. You might notice a few particularly specific arbitray-seeming methods

hydroflow_lang/src/graph/mod.rs

@@ -190,9 +190,10 @@ pub struct OpInstGenerics {
     pub type_args: Vec<Type>,
 }
 
-/// Gets the generic arguments for the operator. This helper method is here due to the special
-/// handling of persistence lifetimes (`'static`, `'tick`, `'mutable`) which must come before
-/// other generic parameters.
+/// Gets the generic arguments for the operator.
+///
+/// This helper method is useful due to the special handling of persistence lifetimes (`'static`,
+/// `'tick`, `'mutable`) which must come before other generic parameters.
 pub fn get_operator_generics(
     diagnostics: &mut Vec<Diagnostic>,
     operator: &Operator,

hydroflow_plus/src/properties.rs

@@ -4,16 +4,25 @@ use stageleft::*;
 
 use crate::ir::{HfPlusLeaf, HfPlusNode, SeenTees};
 
-/// schema : table per algebraic property with the list of expressions that satisfy the property
-/// interface: can "tag" an expression with a property and it will add it to that table
-/// can also run a check to see if an expression satisfies a property
+/// Structure for tracking expressions known to have particular algebraic properties.
+///
+/// # Schema
+///
+/// Each field in this struct corresponds to an algebraic property, and contains the list of
+/// expressions that satisfy the property. Currently only `commutative`.
+///
+/// # Interface
+///
+/// "Tag" an expression with a property and it will add it to that table. For example, [`Self::add_commutative_tag`].
+/// Can also run a check to see if an expression satisfies a property.
 #[derive(Default)]
 pub struct PropertyDatabase {
     commutative: HashSet<syn::Expr>,
 }
 
+/// Allows us to convert the hydroflow datatype for folds to a binary operation for the algebra
+/// property tests.
 #[allow(dead_code)]
-// allows us to convert the hydroflow datatype for folds to a binary operation for the algebra property tests
 fn convert_hf_to_binary<I, A: Default, F: Fn(&mut A, I)>(f: F) -> impl Fn(I, I) -> A {
     move |a, b| {
         let mut acc = Default::default();
@@ -24,6 +33,7 @@ fn convert_hf_to_binary<I, A: Default, F: Fn(&mut A, I)>(f: F) -> impl Fn(I, I)
 }
 
 impl PropertyDatabase {
+    /// Tags the expression as commutative.
     pub fn add_commutative_tag<'a, I, A, F: Fn(&mut A, I), Q: Quoted<'a, F> + Clone>(
         &mut self,
         expr: Q,