iter::Timestamp: document qualities, relation to overflows

Author: tmplt

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `iter::Timestamps`: associate the timestamp data relation (now termed "quality") with a wrapping enum instead.
   For example, a previous `Timestamp { offset: 1, data_relation: Sync }` is now represented as `Timestamp::Sync(1)`.
   This change greatly encourages the downstream user to handle all timestamp qualities.
+- Improved `iter::Timestamps` documentation regarding timestamp quality.
 
 ## [v0.7.0] - 2022-01-17
 

itm/src/iter.rs

@@ -81,7 +81,18 @@ pub struct TimestampedTracePackets {
     pub consumed_packets: usize,
 }
 
-/// Absolute timestamp with quality description. Also see (Appendix D4.2.4).
+/// Timestamp relative to trace clock start with quality
+/// descriptions. In order of decreasing quality:
+/// - [`Sync`](Timestamp::Sync);
+/// - [`UnknownDelay`](Timestamp::UnknownDelay);
+/// - [`AssocEventDelay`](Timestamp::AssocEventDelay);
+/// - [`UnknownAssocEventDelay`](Timestamp::UnknownAssocEventDelay).
+///
+/// A decrease in timestamp quality indicates an insufficient
+/// exfiltration rate of trace packets. A decrease in timestamp
+/// quality may herald an overflow event.
+///
+/// See also (Appendix D4.2.4).
 #[derive(Debug, Clone, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub enum Timestamp {