basic docs for action high-level modules

satrs/src/pus/action.rs

@@ -8,6 +8,21 @@ use super::verification::{TcStateAccepted, VerificationReporterWithSender, Verif
 #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 pub use std_mod::*;
 
+/// This trait is an abstraction for the conversion of a PUS service 8 action telecommand into
+/// an [ActionRequest].
+///
+/// Having a dedicated trait for this allows maximum flexiblity and tailoring of the standard.
+/// The only requirement is that a valid [TargetId] and an [ActionRequest] are returned by the
+/// core conversion function.
+///
+/// The user should take care of performing the error handling as well. Some of the following
+/// aspects might be relevant:
+///
+/// - Checking the validity of the APID, service ID, subservice ID.
+/// - Checking the validity of the user data.
+///
+/// A [VerificationReporterWithSender] instance is passed to the user to also allow handling
+/// of the verification process as part of the PUS standard requirements.
 pub trait PusActionToRequestConverter {
     type Error;
     fn convert(
@@ -19,6 +34,8 @@ pub trait PusActionToRequestConverter {
     ) -> Result<(TargetId, ActionRequest), Self::Error>;
 }
 
+/// This trait is an abstraction for the routing of PUS service 8 action requests to a dedicated
+/// recipient using the generic [TargetId].
 pub trait PusActionRequestRouter {
     type Error;
     fn route(
@@ -39,6 +56,16 @@ pub mod std_mod {
 
     use super::*;
 
+    /// This is a high-level handler for the PUS service 8 action service.
+    ///
+    /// It performs the following handling steps:
+    ///
+    /// 1. Retrieve the next TC packet from the [PusServiceHelper]. The [EcssTcInMemConverter]
+    ///    allows to configure the used telecommand memory backend.
+    /// 2. Convert the TC to a targeted action request using the provided
+    ///    [PusActionToRequestConverter].
+    /// 3. Route the action request using the provided [PusActionRequestRouter].
+    /// 4. Handle all routing errors using the provided [PusRoutingErrorHandler].
     pub struct PusService8ActionHandler<
         TcInMemConverter: EcssTcInMemConverter,
         RequestConverter: PusActionToRequestConverter,
@@ -78,6 +105,7 @@ pub mod std_mod {
             }
         }
 
+        /// Core function to poll the next TC packet and try to handle it.
         pub fn handle_one_tc(&mut self) -> Result<PusPacketHandlerResult, PusPacketHandlingError> {
             let possible_packet = self.service_helper.retrieve_and_accept_next_packet()?;
             if possible_packet.is_none() {