docs(hydro_lang)!: rename singleton_first_tick to `optional_first_t…

…ick` and add example of doctest (#1659)

hydro_lang/src/location/tick.rs

@@ -123,7 +123,7 @@ impl<'a, L: Location<'a>> Tick<L> {
         }
     }
 
-    pub fn singleton_first_tick<T: Clone>(
+    pub fn optional_first_tick<T: Clone>(
         &self,
         e: impl QuotedWithContext<'a, T, Tick<L>>,
     ) -> Optional<T, Self, Bounded>

hydro_lang/src/optional.rs

@@ -197,6 +197,24 @@ impl<'a, T: Clone, L: Location<'a>, B> Clone for Optional<T, L, B> {
 }
 
 impl<'a, T, L: Location<'a>, B> Optional<T, L, B> {
+    /// Transforms the optional value by applying a function `f` to it,
+    /// continuously as the input is updated.
+    ///
+    /// Whenever the optional is empty, the output optional is also empty.
+    ///
+    /// # Example
+    /// ```rust
+    /// # use hydro_lang::*;
+    /// # use dfir_rs::futures::StreamExt;
+    /// # tokio_test::block_on(test_util::stream_transform_test(|process| {
+    /// let tick = process.tick();
+    /// let optional = tick.optional_first_tick(q!(1));
+    /// optional.map(q!(|v| v + 1)).all_ticks().drop_timestamp()
+    /// # }, |mut stream| async move {
+    /// // 2
+    /// # assert_eq!(stream.next().await.unwrap(), 2);
+    /// # }));
+    /// ```
     pub fn map<U, F: Fn(T) -> U + 'a>(self, f: impl IntoQuotedMut<'a, F, L>) -> Optional<U, L, B> {
         let f = f.splice_fn1_ctx(&self.location).into();
         Optional::new(

hydro_test/src/cluster/bench_client.rs

@@ -19,7 +19,7 @@ pub fn bench_client<'a>(
     // r_to_clients_payload_applied.clone().inspect(q!(|payload: &(u32, ReplicaPayload)| println!("Client received payload: {:?}", payload)));
 
     // Set up an initial set of payloads on the first tick
-    let start_this_tick = client_tick.singleton_first_tick(q!(()));
+    let start_this_tick = client_tick.optional_first_tick(q!(()));
 
     let c_new_payloads_on_start = start_this_tick.clone().flat_map_ordered(q!(move |_| (0
         ..num_clients_per_node)