complete basic documentation

src/dest.rs

@@ -1,10 +1,34 @@
-//! CFDP Destination Entity Module
+//! # CFDP Destination Entity Module
 //!
 //! The [DestinationHandler] is the primary component of this module which converts the PDUs sent
 //! from a remote source entity back to a file. A file copy operation on the receiver side
 //! is started with the reception of a Metadata PDU, for example one generated by the
 //! [spacepackets::cfdp::pdu::metadata::MetadataPduCreator]. After that, file packet PDUs, for
-//! example generated with the [spacepackets::cfdp::pdu::file_data] module.
+//! example generated with the [spacepackets::cfdp::pdu::file_data] module, can be inserted into
+//! the destination handler and will be assembled into a file.
+//!
+//! A destination entity might still generate packets which need to be sent back to the source
+//! entity of the file transfer. However, this handler allows freedom of communication like the
+//! source entity by using a user-provided [PduSendProvider] to send all generated PDUs.
+//!
+//! The transaction will be finished when following conditions are met:
+//!
+//!  1. A valid EOF PDU, for example one generated by the [spacepackets::cfdp::pdu::eof::EofPdu]
+//!     helper, has been inserted into the class.
+//!  2. The file checksum verification has been successful. If this is not the case for the
+//!     unacknowledged mode, the handler will re-attempt the checksum calculation up to a certain
+//!     threshold called the check limit. If the threshold is reached, the transaction will
+//!     finish with a failure.
+//!
+//! ### Unacknowledged mode with closure
+//!
+//!  3. Finished PDU has been sent back to the remote side.
+//!
+//! ### Acknowledged mode
+//!
+//!  3. An EOF ACK PDU has been sent back to the remote side.
+//!  4. A Finished PDU has been sent back to the remote side.
+//!  5. A Finished PDU ACK was received.
 use crate::{user::TransactionFinishedParams, DummyPduProvider, GenericSendError, PduProvider};
 use core::str::{from_utf8, from_utf8_unchecked, Utf8Error};