From 4b5b11486e0e38af3b51582b2a43a972aa639697 Mon Sep 17 00:00:00 2001 From: Robin Mueller Date: Wed, 26 Oct 2022 00:23:10 +0200 Subject: [PATCH] doc cfg support --- fsrc-core/Cargo.toml | 4 +++ fsrc-core/src/event_man.rs | 2 +- fsrc-core/src/events.rs | 41 +++++++++++++++++++++++++++---- fsrc-core/src/lib.rs | 3 +++ fsrc-core/src/pus/event_man.rs | 9 ++++--- fsrc-core/src/pus/verification.rs | 4 +-- spacepackets | 2 +- 7 files changed, 53 insertions(+), 12 deletions(-) diff --git a/fsrc-core/Cargo.toml b/fsrc-core/Cargo.toml index 69df909..35072fe 100644 --- a/fsrc-core/Cargo.toml +++ b/fsrc-core/Cargo.toml @@ -42,3 +42,7 @@ default = ["std"] std = ["downcast-rs/std", "alloc", "bus", "postcard/use-std", "crossbeam-channel/std"] alloc = [] heapless = [] + +[package.metadata.docs.rs] +all-features = true +rustdoc-args = ["--cfg", "doc_cfg"] diff --git a/fsrc-core/src/event_man.rs b/fsrc-core/src/event_man.rs index 5d1c6ba..33884b6 100644 --- a/fsrc-core/src/event_man.rs +++ b/fsrc-core/src/event_man.rs @@ -1,4 +1,4 @@ -//! [Event][crate::events::Event] management and forwarding +//! Event management and forwarding use crate::events::{EventU16TypedSev, EventU32, GenericEvent, HasSeverity}; use alloc::boxed::Box; use alloc::vec; diff --git a/fsrc-core/src/events.rs b/fsrc-core/src/events.rs index b2dbec8..02f4dfd 100644 --- a/fsrc-core/src/events.rs +++ b/fsrc-core/src/events.rs @@ -1,5 +1,32 @@ //! Event support module - +//! +//! This module includes the basic event structs [EventU32] and [EventU16] and versions with the +//! ECSS severity levels as a type parameter. These structs are simple abstractions on top of the +//! [u32] and [u16] types where the raw value is the unique identifier for a particular event. +//! The abstraction also allows to group related events using a group ID, and the severity +//! of an event is encoded inside the raw value itself with four possible [Severity] levels: +//! +//! - INFO +//! - LOW +//! - MEDIUM +//! - HIGH +//! +//! All event structs implement the [EcssEnumeration] trait and can be created as constants. +//! This allows to easily create a static list of constant events which can then be used to generate +//! event telemetry using the PUS event manager modules. +//! +//! # Examples +//! +//! ``` +//! use fsrc_core::events::{EventU16, EventU32, EventU32TypedSev, Severity, SeverityHigh, SeverityInfo}; +//! +//! const MSG_RECVD: EventU32TypedSev = EventU32TypedSev::const_new(1, 0); +//! const MSG_FAILED: EventU32 = EventU32::const_new(Severity::LOW, 1, 1); +//! +//! const TEMPERATURE_HIGH: EventU32TypedSev = EventU32TypedSev::const_new(2, 0); +//! +//! let small_event = EventU16::new(Severity::INFO, 3, 0); +//! ``` use core::hash::Hash; use delegate::delegate; use spacepackets::ecss::{EcssEnumeration, ToBeBytes}; @@ -23,24 +50,28 @@ pub trait HasSeverity { const SEVERITY: Severity; } +/// Type level support struct #[derive(Debug, PartialEq, Eq)] pub struct SeverityInfo {} impl HasSeverity for SeverityInfo { const SEVERITY: Severity = Severity::INFO; } +/// Type level support struct #[derive(Debug, PartialEq, Eq)] pub struct SeverityLow {} impl HasSeverity for SeverityLow { const SEVERITY: Severity = Severity::LOW; } +/// Type level support struct #[derive(Debug, PartialEq, Eq)] pub struct SeverityMedium {} impl HasSeverity for SeverityMedium { const SEVERITY: Severity = Severity::MEDIUM; } +/// Type level support struct #[derive(Debug, PartialEq, Eq)] pub struct SeverityHigh {} impl HasSeverity for SeverityHigh { @@ -76,7 +107,7 @@ impl TryFrom for Severity { } #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] -pub struct EventBase { +struct EventBase { severity: Severity, group_id: GID, unique_id: UID, @@ -322,7 +353,7 @@ impl EventU32TypedSev { }) } - /// Const version of [new], but panics on invalid group ID input values. + /// Const version of [Self::new], but panics on invalid group ID input values. pub const fn const_new( group_id: ::GroupId, unique_id: ::UniqueId, @@ -421,7 +452,7 @@ impl EventU16 { }) } - /// Const version of [new], but panics on invalid group ID input values. + /// Const version of [Self::new], but panics on invalid group ID input values. pub const fn const_new( severity: Severity, group_id: ::GroupId, @@ -459,7 +490,7 @@ impl EventU16TypedSev { }) } - /// Const version of [new], but panics on invalid group ID input values. + /// Const version of [Self::new], but panics on invalid group ID input values. pub const fn const_new( group_id: ::GroupId, unique_id: ::UniqueId, diff --git a/fsrc-core/src/lib.rs b/fsrc-core/src/lib.rs index 02298a0..e8349da 100644 --- a/fsrc-core/src/lib.rs +++ b/fsrc-core/src/lib.rs @@ -15,13 +15,16 @@ extern crate std; pub mod error; #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] pub mod event_man; pub mod events; #[cfg(feature = "std")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "std")))] pub mod executable; pub mod hal; pub mod objects; #[cfg(feature = "alloc")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))] pub mod pool; pub mod pus; pub mod tmtc; diff --git a/fsrc-core/src/pus/event_man.rs b/fsrc-core/src/pus/event_man.rs index 86581f6..5b48143 100644 --- a/fsrc-core/src/pus/event_man.rs +++ b/fsrc-core/src/pus/event_man.rs @@ -6,12 +6,14 @@ use hashbrown::HashSet; use crate::pus::event::EventReporter; use crate::pus::{EcssTmError, EcssTmSender}; #[cfg(feature = "heapless")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "heapless")))] pub use heapless_mod::*; /// This trait allows the PUS event manager implementation to stay generic over various types -/// of backend containers. These backend containers keep track on whether a particular event -/// is enabled or disabled for reporting and also expose a simple API to enable or disable the event -/// reporting. +/// of backend containers. +/// +/// These backend containers keep track on whether a particular event is enabled or disabled for +/// reporting and also expose a simple API to enable or disable the event reporting. /// /// For example, a straight forward implementation for host systems could use a /// [hash set](https://docs.rs/hashbrown/latest/hashbrown/struct.HashSet.html) @@ -59,6 +61,7 @@ pub mod heapless_mod { use crate::events::{GenericEvent, LargestEventRaw}; use std::marker::PhantomData; + #[cfg_attr(doc_cfg, doc(cfg(feature = "heapless")))] // TODO: After a new version of heapless is released which uses hash32 version 0.3, try using // regular Event type again. #[derive(Default)] diff --git a/fsrc-core/src/pus/verification.rs b/fsrc-core/src/pus/verification.rs index 479dc11..41b74e1 100644 --- a/fsrc-core/src/pus/verification.rs +++ b/fsrc-core/src/pus/verification.rs @@ -987,7 +987,7 @@ mod stdmod { } /// Verification sender with a [mpsc::Sender] backend. - /// It implements the [VerificationSender] trait to be used as PUS Verification TM sender. + /// It implements the [EcssTmSender] trait to be used as PUS Verification TM sender. impl MpscVerifSender { pub fn new(tm_store: SharedPool, tx: mpsc::Sender) -> Self { Self { @@ -1014,7 +1014,7 @@ mod stdmod { } /// Verification sender with a [crossbeam_channel::Sender] backend. - /// It implements the [VerificationSender] trait to be used as PUS Verification TM sender + /// It implements the [EcssTmSender] trait to be used as PUS Verification TM sender pub struct CrossbeamVerifSender { base: StdSenderBase>, } diff --git a/spacepackets b/spacepackets index a2673c9..65e85f2 160000 --- a/spacepackets +++ b/spacepackets @@ -1 +1 @@ -Subproject commit a2673c98707ecbbabb9535bef607025c92b54724 +Subproject commit 65e85f20e03507f19a0d5086ee19360ff7596c27