Documentation

src/signing/petition_types/petition_factors_types/neglected_factor_instance.rs

@@ -1,6 +1,33 @@
 use crate::prelude::*;
 
+/// A neglected factor, with a reason.
+#[derive(Clone, PartialEq, Eq, Hash)]
+pub struct AbstractNeglectedFactor<T> {
+    /// The reason why this factor was neglected.
+    pub reason: NeglectFactorReason,
+
+    /// The neglected factor
+    pub content: T,
+}
+
+impl<T> AbstractNeglectedFactor<T> {
+    pub fn new(reason: NeglectFactorReason, content: T) -> Self {
+        Self { reason, content }
+    }
+}
+
+impl<T: std::fmt::Debug> std::fmt::Debug for AbstractNeglectedFactor<T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Neglected")
+            .field("reason", &self.reason)
+            .field("content", &self.content)
+            .finish()
+    }
+}
+
 impl NeglectedFactorInstance {
+    /// Maps from `Neglected<HierarchicalDeterministicFactorInstance>`
+    /// to `Neglected<FactorSourceIDFromHash>`,
     pub fn as_neglected_factor(&self) -> NeglectedFactor {
         NeglectedFactor::new(self.reason, self.factor_source_id())
     }
@@ -32,36 +59,25 @@ impl HasSampleValues for NeglectedFactorInstance {
     }
 }
 
+/// ID to some neglected factor source, with the reason why it was neglected (skipped/failed)
 pub type NeglectedFactor = AbstractNeglectedFactor<FactorSourceIDFromHash>;
-pub type NeglectedFactors = AbstractNeglectedFactor<IndexSet<FactorSourceIDFromHash>>;
-pub type NeglectedFactorInstance = AbstractNeglectedFactor<HierarchicalDeterministicFactorInstance>;
 
-#[derive(Clone, PartialEq, Eq, Hash)]
-pub struct AbstractNeglectedFactor<T> {
-    pub reason: NeglectFactorReason,
-    pub content: T,
-}
-impl<T> AbstractNeglectedFactor<T> {
-    pub fn new(reason: NeglectFactorReason, content: T) -> Self {
-        Self { reason, content }
-    }
-}
+/// IDs to some neglected factor source, with the reason why they were neglected (skipped/failed)
+pub type NeglectedFactors = AbstractNeglectedFactor<IndexSet<FactorSourceIDFromHash>>;
 
-impl<T: std::fmt::Debug> std::fmt::Debug for AbstractNeglectedFactor<T> {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("Neglected")
-            .field("reason", &self.reason)
-            .field("content", &self.content)
-            .finish()
-    }
-}
+/// A HierarchicalDeterministicFactorInstance which was rejected, with the reason why (skipped/failed)
+pub type NeglectedFactorInstance = AbstractNeglectedFactor<HierarchicalDeterministicFactorInstance>;
 
+/// Reason why some FactorSource was neglected, either explicitly skipped by the user
+/// or implicitly neglected due to failure.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, derive_more::Debug, derive_more::Display)]
 pub enum NeglectFactorReason {
+    /// A FactorSource got neglected since user explicitly skipped it.
     #[display("User Skipped")]
     #[debug("UserExplicitlySkipped")]
     UserExplicitlySkipped,
 
+    /// A FactorSource got neglected implicitly due to failure
     #[display("Failure")]
     #[debug("Failure")]
     Failure,