From 9bea82ff0e6938b30105287aa902c013a3a9bcdc Mon Sep 17 00:00:00 2001
From: Robin Mueller <robin.mueller.m@gmail.com>
Date: Wed, 31 Jan 2024 15:19:18 +0100
Subject: [PATCH] add some documentation

---
 satrs-core/Cargo.toml              |  3 ++-
 satrs-core/src/pus/mod.rs          | 25 ++++++++++++++++++-------
 satrs-core/src/pus/verification.rs |  2 ++
 3 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/satrs-core/Cargo.toml b/satrs-core/Cargo.toml
index d16f0a0..dcd9e77 100644
--- a/satrs-core/Cargo.toml
+++ b/satrs-core/Cargo.toml
@@ -123,4 +123,5 @@ doc-images = []
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--cfg", "doc_cfg"]
+targets = ["x86_64-unknown-linux-gnu"]
+rustdoc-args = ["--cfg", "doc_cfg", "--generate-link-to-definition"]
diff --git a/satrs-core/src/pus/mod.rs b/satrs-core/src/pus/mod.rs
index 9361eed..caf6f39 100644
--- a/satrs-core/src/pus/mod.rs
+++ b/satrs-core/src/pus/mod.rs
@@ -194,6 +194,9 @@ pub trait EcssTcSenderCore: EcssChannel {
     fn send_tc(&self, tc: PusTcCreator, token: Option<TcStateToken>) -> Result<(), EcssTmtcError>;
 }
 
+/// A PUS telecommand packet can be stored in memory using different methods. Right now,
+/// storage inside a pool structure like [LocalPool], and storage inside a `Vec<u8>` are
+/// supported.
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum TcInMemory {
@@ -215,6 +218,7 @@ impl From<alloc::vec::Vec<u8>> for TcInMemory {
     }
 }
 
+/// Generic structure for an ECSS PUS Telecommand and its correspoding verification token.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct EcssTcAndToken {
     pub tc_in_memory: TcInMemory,
@@ -363,6 +367,7 @@ mod alloc_mod {
 }
 
 #[cfg(feature = "std")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 pub mod std_mod {
     use crate::pool::{SharedPool, StoreAddr};
     use crate::pus::verification::{
@@ -705,7 +710,7 @@ pub mod std_mod {
         }
     }
 
-    /// Converter structure for PUS telecommands which are stored inside a [Vec<u8>] structure.
+    /// Converter structure for PUS telecommands which are stored inside a `Vec<u8>` structure.
     /// Please note that this structure is not able to convert TCs which are stored inside a
     /// [SharedPool].
     pub struct EcssTcInVecConverter {
@@ -827,12 +832,13 @@ pub mod std_mod {
         }
     }
 
-    /// Base class for handlers which can handle PUS TC packets. Right now, the verification
-    /// reporter is constrained to the [StdVerifReporterWithSender] and the service handler
-    /// relies on TMTC packets being exchanged via a [SharedPool]. Please note that this variant
-    /// of the PUS service base is not optimized for handling packets sent as a `Vec<u8>` and
-    /// might perform additional copies to the internal buffer as well. The class should
-    /// still behave correctly.
+    /// This is a high-level PUS packet handler. It performs some of the boilerplate acitivities
+    /// involved when handling PUS telecommands and it can be used to implement the handling of
+    /// PUS telecommands for certain PUS telecommands groups (for example individual services).
+    ///
+    /// This base class can handle PUS telecommands backed by different memory storage machanisms
+    /// by using the [EcssTcInMemConverter] abstraction. This object provides some convenience
+    /// methods to make the generic parts of TC handling easier.
     pub struct PusServiceHandler<TcInMemConverter: EcssTcInMemConverter> {
         pub common: PusServiceBase,
         pub tc_in_mem_converter: TcInMemConverter,
@@ -857,6 +863,11 @@ pub mod std_mod {
             }
         }
 
+        /// This function can be used to poll the internal [EcssTcReceiver] object for the next
+        /// telecommand packet. It will return `Ok(None)` if there are not packets available.
+        /// In any other case, it will perform the acceptance of the ECSS TC packet using the
+        /// internal [VerificationReporterWithSender] object. It will then return the telecommand
+        /// and the according accepted token.
         pub fn retrieve_and_accept_next_packet(
             &mut self,
         ) -> Result<Option<AcceptedEcssTcAndToken>, PusPacketHandlingError> {
diff --git a/satrs-core/src/pus/verification.rs b/satrs-core/src/pus/verification.rs
index ff38b89..77261fe 100644
--- a/satrs-core/src/pus/verification.rs
+++ b/satrs-core/src/pus/verification.rs
@@ -208,6 +208,8 @@ impl WasAtLeastAccepted for TcStateAccepted {}
 impl WasAtLeastAccepted for TcStateStarted {}
 impl WasAtLeastAccepted for TcStateCompleted {}
 
+/// Token wrapper to model all possible verification tokens. These tokens are used to
+/// enforce the correct order for the verification steps when doing verification reporting.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 pub enum TcStateToken {
     None(VerificationToken<TcStateNone>),