docs(core): add documentation for all public API members

argus-core/src/lib.rs

@@ -1,3 +1,15 @@
+//! # `argus-core`
+//!
+//! This crate provides some of the core functionality or interfaces for the other Argus
+//! components. Mainly, the crate provides:
+//!
+//! 1. Expression tree nodes for defining temporal logic specifications (see [`expr`]).
+//! 2. Different signal types for generating traces of data (see [`signals`]).
+//! 3. A list of possible errors any component in Argus can generate (see
+//!    [`enum@Error`]).
+
+#![warn(missing_docs)]
+
 pub mod expr;
 pub mod prelude;
 pub mod signals;
@@ -6,33 +18,68 @@ use std::time::Duration;
 
 use thiserror::Error;
 
+/// Errors generated by all Argus components.
 #[derive(Error, Debug)]
 pub enum Error {
+    /// An identifier has been redeclared in a specification.
+    ///
+    /// This is called mainly from [`expr::ExprBuilder`].
     #[error("redeclaration of identifier")]
     IdentifierRedeclaration,
+
+    /// An expression is provided with an insufficient number of arguments.
+    ///
+    /// This is called for N-ary expressions:
+    /// [`NumExpr::Add`](crate::expr::NumExpr::Add),
+    /// [`NumExpr::Mul`](crate::expr::NumExpr::Mul),
+    /// [`BoolExpr::And`](crate::expr::BoolExpr::And), and
+    /// [`BoolExpr::Or`](crate::expr::BoolExpr::Or).
     #[error("insufficient number of arguments")]
     IncompleteArgs,
 
+    /// Attempting to `push` a new sample to a non-sampled signal
+    /// ([`Signal::Empty`](crate::signals::Signal::Empty) or
+    /// [`Signal::Constant`](crate::signals::Signal::Constant)).
     #[error("cannot push value to non-sampled signal")]
     InvalidPushToSignal,
+
+    /// Pushing the new value to the sampled signal makes it not strictly monotonically
+    /// increasing.
     #[error(
         "trying to create a non-monotonically signal, signal end time ({end_time:?}) > sample time point \
          ({current_sample:?})"
     )]
-    NonMonotonicSignal { end_time: Duration, current_sample: Duration },
+    NonMonotonicSignal {
+        /// The time that the signal actually ends
+        end_time: Duration,
+        /// The time point of the new (erroneous) sample.
+        current_sample: Duration,
+    },
 
-    #[error("invalid operation due to bad type")]
+    /// Attempting to perform an invalid operation on a signal
+    #[error("invalid operation on signal")]
     InvalidOperation,
 
+    /// Attempting to index a signal not present in a trace (see
+    /// [`mod@argus_semantics::Trace`].
     #[error("name not in signal trace")]
     SignalNotPresent,
 
+    /// Attempting to perform a signal operation not supported by the type
     #[error("incorrect signal type")]
     InvalidSignalType,
 
+    /// Incorrect cast of signal
     #[error("invalid cast from {from} to {to}")]
-    InvalidCast { from: &'static str, to: &'static str },
+    InvalidCast {
+        /// Type of the signal being cast from
+        from: &'static str,
+        /// Type of the signal being cast to
+        to: &'static str,
+    },
 }
 
+/// Alias for [`Error`](enum@Error)
 pub type ArgusError = Error;
+/// Alias for [`Result<T, ArgusError>`]
 pub type ArgusResult<T> = Result<T, Error>;