remove one more path dependency

src/source.rs

@@ -32,6 +32,7 @@ use super::{
     RemoteEntityConfigProvider, State, TransactionId, UserFaultHookProvider,
 };
 
+/// This enumeration models the different transaction steps of the source entity handler.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum TransactionStep {
@@ -137,6 +138,33 @@ pub enum PutRequestError {
     FilestoreError(#[from] FilestoreError),
 }
 
+/// This is the primary CFDP source handler. It models the CFDP source entity, which is
+/// primarily responsible for handling put requests to send files to another CFDP destination
+/// entity.
+///
+/// As such, it contains a state machine to perform all operations necessary to perform a
+/// source-to-destination file transfer. This class uses the user provides [PduSendProvider] to
+/// send the CFDP PDU packets generated by the state machine.
+///
+/// The following core functions are the primary interface:
+///
+/// 1. [Self::put_request] can be used to start transactions, most notably to start
+///    and perform a Copy File procedure to send a file or to send a Proxy Put Request to request
+///    a file.
+/// 2. [Self::state_machine] is the primary interface to execute an
+///    active file transfer. It generates the necessary CFDP PDUs for this process.
+///    This method is also used to insert received packets with the appropriate destination ID
+///    and target handler type into the state machine.
+///
+/// A put request will only be accepted if the handler is in the idle state.
+///
+/// The handler requires the [alloc] feature but will allocated all required memory on construction
+/// time. This means that the handler is still suitable for embedded systems where run-time
+/// allocation is prohibited. Furthermore, it uses the [VirtualFilestore] abstraction to allow
+/// usage on systems without a [std] filesystem.
+/// This handler does not support concurrency out of the box. Instead, if concurrent handling
+/// is required, it is recommended to create a new handler and run all active handlers inside a
+/// thread pool, or move the newly created handler to a new thread.
 pub struct SourceHandler<
     PduSender: PduSendProvider,
     UserFaultHook: UserFaultHookProvider,
@@ -168,6 +196,25 @@ impl<
         SeqCountProvider: SequenceCountProvider,
     > SourceHandler<PduSender, UserFaultHook, Vfs, RemoteCfgTable, SeqCountProvider>
 {
+    /// Creates a new instance of a source handler.
+    ///
+    /// # Arguments
+    ///
+    /// * `cfg` - The local entity configuration for this source handler.
+    /// * `pdu_sender` - [PduSendProvider] provider used to send CFDP PDUs generated by the handler.
+    /// * `vfs` - [VirtualFilestore] implementation used by the handler, which decouples the CFDP
+    ///    implementation from the underlying filestore/filesystem. This allows to use this handler
+    ///    for embedded systems where a standard runtime might not be available.
+    /// * `put_request_cacher` - The put request cacher is used cache put requests without
+    ///    requiring run-time allocation.
+    /// * `pdu_and_cksum_buf_size` - The handler requires a buffer to generate PDUs and perform
+    ///    checksum calculations. The user can specify the size of this buffer, so this should be
+    ///    set to the maximum expected PDU size or a conservative upper bound for this size, for
+    ///    example 2048 or 4096 bytes.
+    /// * `remote_cfg_table` - The [RemoteEntityConfigProvider] used to look up remote
+    ///    entities and target specific configuration for file copy operations.
+    /// * `seq_count_provider` - The [SequenceCountProvider] used to generate the [TransactionId]
+    ///    which contains an incrementing counter.
     pub fn new(
         cfg: LocalEntityConfig<UserFaultHook>,
         pdu_sender: PduSender,
@@ -192,6 +239,7 @@ impl<
         }
     }
 
+    /// Calls [Self::state_machine], without inserting a packet.
     pub fn state_machine_no_packet(
         &mut self,
         cfdp_user: &mut impl CfdpUser,
@@ -271,6 +319,13 @@ impl<
         Ok(())
     }
 
+    /// This function is used to pass a put request to the source handler, which is
+    /// also used to start a file copy operation. As such, this function models the Put.request
+    /// CFDP primtiive.
+
+    /// Please note that the source handler can also process one put request at a time.
+    /// The caller is responsible of creating a new source handler, one handler can only handle
+    /// one file copy request at a time.
     pub fn put_request(
         &mut self,
         put_request: &impl ReadablePutRequest,
@@ -348,6 +403,7 @@ impl<
         derived_max_seg_len as u64
     }
 
+    /// Returns the [TransmissionMode] for the active file operation.
     #[inline]
     pub fn transmission_mode(&self) -> Option<super::TransmissionMode> {
         self.tstate.as_ref().map(|v| v.transmission_mode)
@@ -366,7 +422,6 @@ impl<
             self.prepare_and_send_metadata_pdu()?;
             self.state_helper.step = TransactionStep::SendingFileData;
             sent_packets += 1;
-            // return Ok(1);
         }
         if self.state_helper.step == TransactionStep::SendingFileData {
             if let ControlFlow::Break(packets) = self.file_data_fsm()? {
@@ -378,7 +433,6 @@ impl<
         if self.state_helper.step == TransactionStep::SendingEof {
             self.eof_fsm(cfdp_user)?;
             sent_packets += 1;
-            // return Ok(1);
         }
         if self.state_helper.step == TransactionStep::WaitingForFinished {
             /*
@@ -768,13 +822,12 @@ impl<
 
     fn handle_keep_alive_pdu(&mut self) {}
 
-    /// Get the step, which denotes the exact step of a pending CFDP transaction when applicable.
+    /// Get the [TransactionStep], which denotes the exact step of a pending CFDP transaction when
+    /// applicable.
     pub fn step(&self) -> TransactionStep {
         self.state_helper.step
     }
 
-    /// Get the step, which denotes whether the CFDP handler is active, and which CFDP class
-    /// is used if it is active.
     pub fn state(&self) -> State {
         self.state_helper.state
     }