[PATCH datacenter-manager 5/5] parallel fetcher: add module documentation

[Lukas Wagner <l.wagner@proxmox.com>]

Adding a (no-run) doctest for the module level documentation gives users
a quick idea on how to use this helper.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 server/src/parallel_fetcher.rs | 65 ++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/server/src/parallel_fetcher.rs b/server/src/parallel_fetcher.rs
index 57011096..0abd9a50 100644
--- a/server/src/parallel_fetcher.rs
+++ b/server/src/parallel_fetcher.rs
@@ -1,3 +1,66 @@
+//! Helpers that can be used to parallelize API requests to remotes.
+//!
+//! ```no_run
+//! # use anyhow::Error;
+//! #
+//! # use pdm_api_types::remotes::{RemoteType, Remote};
+//! # use server::parallel_fetcher::ParallelFetcher;
+//! #
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), Error> {
+//! #   let remotes: Vec<Remote> = Vec::new();
+//! #
+//!     async fn fetch_meaning(
+//!         _context: (),
+//!         remote: Remote,
+//!         node: String,
+//!     ) -> Result<i32, Error> {
+//!         match remote.ty {
+//!             RemoteType::Pve => {
+//!                 // Perform the API request here and return some result.
+//!                 Ok(42)
+//!             },
+//!             RemoteType::Pbs => Ok(42),
+//!         }
+//!     }
+//!
+//!     // This context can be passed to the function what is executed for every remote node.
+//!     let context = ();
+//!
+//!     let fetcher = ParallelFetcher::builder(context)
+//!         .max_connections(10)
+//!         .max_connections_per_remote(2)
+//!         .build();
+//!
+//!     let fetch_result = fetcher
+//!         .do_for_all_remote_nodes(remotes.into_iter(), fetch_meaning)
+//!         .await;
+//!
+//!     for remote_outcome in fetch_result {
+//!         match remote_outcome.nodes() {
+//!             Ok(node_outcomes) => {
+//!                 for node_outcome in node_outcomes {
+//!                     match node_outcome.data() {
+//!                         Ok(meaning) => assert_eq!(*meaning, 42),
+//!                         Err(err) =>
+//!                             log::error!(
+//!                                 "failed to retrieve result for node {}",
+//!                                 node_outcome.node_name()
+//!                             ),
+//!                     }
+//!                 }
+//!             }
+//!             Err(err) => log::error!(
+//!                 "failed to connect to remote {}",
+//!                 remote_outcome.remote()
+//!             ),
+//!         }
+//!     }
+//!
+//! #   Ok(())
+//! # }
+//! ```
+
 use std::fmt::Debug;
 use std::future::Future;
 use std::sync::Arc;
@@ -14,7 +77,9 @@ use pdm_api_types::remotes::{Remote, RemoteType};
 
 use crate::connection;
 
+/// Maximum number of parallel outgoing API requests.
 pub const DEFAULT_MAX_CONNECTIONS: usize = 20;
+/// Maximum number of parallel outgoing API requests to the *same* remote.
 pub const DEFAULT_MAX_CONNECTIONS_PER_REMOTE: usize = 5;
 
 /// Outcome type produced by [`ParallelFetcher::do_for_all_remotes`] or
-- 
2.47.3